@wherever-dev/client 0.5.4 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/client.ts CHANGED
@@ -1,5 +1,11 @@
1
1
  import { writable, get, type Writable } from "sveltore";
2
- import { type ChatMessage, type WhereverState, skillInvocationIdentity } from "./types.js";
2
+ import {
3
+ type ChatMessage,
4
+ type RestoreInfo,
5
+ type RestoreJobInfo,
6
+ type WhereverState,
7
+ skillInvocationIdentity,
8
+ } from "./types.js";
3
9
 
4
10
  /**
5
11
  * Per-send options for a user message.
@@ -22,6 +28,29 @@ export interface WhereverClientConfig {
22
28
  WebSocketCtor?: any;
23
29
  hideThinking?: boolean;
24
30
  hideTools?: boolean;
31
+ // Stable identity for THIS viewer across reconnects. The server keys its
32
+ // per-connection client records by socket, so a silently dropped socket (phone
33
+ // sleep, network switch, half-open TCP) leaves a PHANTOM client attached to
34
+ // the session until the heartbeat reaper notices, up to a minute later. In
35
+ // that window the phantom counts as "another viewer", which turns an explicit
36
+ // "New Session Here" into a folder conflict (read-only attach to the existing
37
+ // session). Sending a stable key lets the server evict this viewer's own
38
+ // previous connection the moment it reconnects. Callers should scope the key
39
+ // per TAB (e.g. sessionStorage), never per browser: two real tabs must stay
40
+ // two distinct viewers. Omitted -> a per-instance key is generated, which
41
+ // already covers in-process reconnects.
42
+ clientKey?: string;
43
+ // Called when the client had to take a NEW clientKey because the server
44
+ // reported this one as superseded (two viewers ended up sharing it). Persist it
45
+ // wherever `clientKey` came from, so the collision is resolved for good rather
46
+ // than re-created on the next reconnect.
47
+ onClientKeyChange?: (key: string) => void;
48
+ }
49
+
50
+ // Per-instance fallback identity: stable for the lifetime of this client object,
51
+ // which is exactly the lifetime across which reconnects happen.
52
+ function generateClientKey(): string {
53
+ return `ck-${Math.random().toString(36).slice(2)}${Date.now().toString(36)}`;
25
54
  }
26
55
 
27
56
  const defaultState: WhereverState = {
@@ -37,7 +66,10 @@ const defaultState: WhereverState = {
37
66
  isStreaming: false,
38
67
  messages: [],
39
68
  clientId: null,
69
+ serverVersion: null,
40
70
  folderConflict: null,
71
+ folderMissing: null,
72
+ restore: null,
41
73
  isInterrupted: false,
42
74
  notice: null,
43
75
  sudoPrompt: null,
@@ -59,6 +91,10 @@ const defaultState: WhereverState = {
59
91
  export class WhereverClient {
60
92
  private ws: any = null;
61
93
  private config: WhereverClientConfig;
94
+ // Identity sent on every connect so the server can retire this viewer's own
95
+ // stale/phantom connection instead of counting it as a second viewer. Replaced
96
+ // (once) if the server reports it as superseded by another live connection.
97
+ private clientKey: string;
62
98
  public stateStore: Writable<WhereverState>;
63
99
  private reconnectTimer: any = null;
64
100
  private agentEndTimeout: any = null;
@@ -144,6 +180,7 @@ export class WhereverClient {
144
180
  secure: true,
145
181
  ...config
146
182
  };
183
+ this.clientKey = this.config.clientKey || generateClientKey();
147
184
  this.stateStore = writable<WhereverState>({
148
185
  ...defaultState,
149
186
  hideThinking: !!this.config.hideThinking,
@@ -178,8 +215,13 @@ export class WhereverClient {
178
215
  const host = this.config.host.startsWith('http')
179
216
  ? this.config.host.replace(/^https?:\/\//, '')
180
217
  : this.config.host;
181
- const tokenQuery = this.config.token ? `?token=${encodeURIComponent(this.config.token)}` : "";
182
- const wsUrl = `${protocol}://${host}:${this.config.port}/ws${tokenQuery}`;
218
+ // clientKey rides on the URL (not a post-connect frame) so the server can
219
+ // evict this viewer's previous connection BEFORE any session traffic is
220
+ // handled, closing the phantom-viewer window entirely.
221
+ const params: string[] = [];
222
+ if (this.config.token) params.push(`token=${encodeURIComponent(this.config.token)}`);
223
+ params.push(`clientKey=${encodeURIComponent(this.clientKey)}`);
224
+ const wsUrl = `${protocol}://${host}:${this.config.port}/ws?${params.join('&')}`;
183
225
 
184
226
  const WebSocketImpl = this.config.WebSocketCtor || (typeof globalThis !== 'undefined' ? (globalThis as any).WebSocket : null);
185
227
 
@@ -706,10 +748,26 @@ export class WhereverClient {
706
748
  connected: true,
707
749
  connecting: false,
708
750
  clientId: msg.clientId,
751
+ serverVersion: msg.serverVersion ?? null,
709
752
  error: null,
710
753
  }));
711
754
  break;
712
755
 
756
+ case 'connection_superseded':
757
+ // A newer connection arrived carrying OUR clientKey, so the server is
758
+ // retiring this socket as a superseded duplicate. Receiving this proves we
759
+ // are alive, i.e. the key is being shared by accident (a duplicated tab
760
+ // clones sessionStorage). Take a fresh identity BEFORE the reconnect the
761
+ // imminent close will schedule, so the two connections stop evicting each
762
+ // other; the owner of the key keeps it and we come back as our own viewer.
763
+ this.clientKey = generateClientKey();
764
+ try {
765
+ this.config.onClientKeyChange?.(this.clientKey);
766
+ } catch (err) {
767
+ console.error('onClientKeyChange failed:', err);
768
+ }
769
+ break;
770
+
713
771
  case 'file_uploaded': {
714
772
  const pending = this.pendingUploads.get(msg.uploadId);
715
773
  if (pending) {
@@ -803,17 +861,22 @@ export class WhereverClient {
803
861
  }
804
862
  break;
805
863
 
806
- case 'queue_update':
864
+ case 'queue_update': {
807
865
  // The server relayed pi's current steer queue. Replace our pending-steer
808
866
  // set outright (it is the full queue): a message whose content is still
809
867
  // in this set is a queued steer that has NOT yet been injected, so the
810
868
  // UI can offer to cancel it. When a queued steer is delivered or
811
869
  // cancelled, a fresh queue_update arrives with it removed.
870
+ const steering: string[] = Array.isArray(msg.steering)
871
+ ? [...msg.steering]
872
+ : [];
812
873
  this.stateStore.update((s: WhereverState) => ({
813
874
  ...s,
814
- pendingSteering: Array.isArray(msg.steering) ? [...msg.steering] : [],
875
+ pendingSteering: steering,
876
+ messages: this.withRestoredQueuedMessages(s.messages, steering),
815
877
  }));
816
878
  break;
879
+ }
817
880
 
818
881
  case 'message_end':
819
882
  this.stateStore.update((s: WhereverState) => {
@@ -856,6 +919,26 @@ export class WhereverClient {
856
919
  // Re-read: confirmDeliveredByContent already updated the store.
857
920
  return get(this.stateStore);
858
921
  }
922
+ // A steer we restored from the queue snapshot has now been injected:
923
+ // this echo IS that bubble, so reconcile onto it (drop the marker)
924
+ // rather than appending a duplicate. Oldest first, since pi delivers
925
+ // the queue in order.
926
+ const restoredQueued = newMessages.find(
927
+ (m) =>
928
+ m.role === 'user' &&
929
+ m.restoredFromQueue &&
930
+ m.content === msg.content,
931
+ );
932
+ if (restoredQueued) {
933
+ return {
934
+ ...s,
935
+ messages: newMessages.map((m) =>
936
+ m.id === restoredQueued.id
937
+ ? {...m, restoredFromQueue: undefined}
938
+ : m,
939
+ ),
940
+ };
941
+ }
859
942
  }
860
943
  // Skill invocations arrive TWICE from the server: first the RAW
861
944
  // `/skill:<name> <args>` (as the immediate message_ack, which already
@@ -1174,7 +1257,11 @@ export class WhereverClient {
1174
1257
  // late session_created for the abandoned load must not clobber what the
1175
1258
  // user is now looking at. A session_created is accepted only when it is
1176
1259
  // the reply we are actually waiting on:
1177
- // - a session_load we issued -> matches pendingLoadFile, OR
1260
+ // - a session_load we issued -> matches pendingLoadFile, by FILE or by
1261
+ // ID (a load may be requested by session ID, e.g. the URL-hash deep
1262
+ // link `/#<sessionId>`; the server resolves it and always replies
1263
+ // with the resolved FILE, so a file-only comparison would reject the
1264
+ // load's own reply and hang the "Loading session..." spinner), OR
1178
1265
  // - a session_new we issued -> creatingSession is true (its target
1179
1266
  // file is unknown until this reply, so pendingLoadFile is null).
1180
1267
  // Anything else (pendingLoadFile set but a different file; or no pending
@@ -1186,7 +1273,8 @@ export class WhereverClient {
1186
1273
  const st = get(this.stateStore);
1187
1274
  const matchesPendingLoad =
1188
1275
  this.pendingLoadFile !== null &&
1189
- msg.sessionFile === this.pendingLoadFile;
1276
+ (msg.sessionFile === this.pendingLoadFile ||
1277
+ msg.sessionId === this.pendingLoadFile);
1190
1278
  const isRequestedCreate =
1191
1279
  this.pendingLoadFile === null && st.creatingSession;
1192
1280
  if (!matchesPendingLoad && !isRequestedCreate) {
@@ -1216,6 +1304,15 @@ export class WhereverClient {
1216
1304
  folderConflict: msg.folderConflict
1217
1305
  ? {cwd: msg.cwd, active: true, continued: false}
1218
1306
  : null,
1307
+ // The session's working folder is gone from this machine: the server
1308
+ // built no agent and refuses every send, so the composer is replaced
1309
+ // by a notice naming the path. Hard (no "Continue anyway"); the
1310
+ // authoritative `folder_missing` frame follows with the same cwd.
1311
+ folderMissing: msg.folderMissing ? {cwd: msg.cwd} : null,
1312
+ // The restore panel's state belongs to the folder we are leaving; the
1313
+ // authoritative `folder_missing` frame below re-creates it for this
1314
+ // session (carrying any job already running for its path).
1315
+ restore: null,
1219
1316
  // pending -> the history is painted now but the live agent is still
1220
1317
  // building; keep the composer disabled (agentPending) until
1221
1318
  // session_ready. A non-pending create (new session, warm reload) is
@@ -1225,9 +1322,19 @@ export class WhereverClient {
1225
1322
  // live updates arrive via 'context_usage').
1226
1323
  contextUsage: msg.contextUsage ?? null,
1227
1324
  // Reset skill-command autocomplete for the newly attached session; the
1228
- // authoritative list is (re-)requested on session_ready.
1325
+ // authoritative list is (re-)requested just below (already-live
1326
+ // session) or on session_ready (cold, still-building agent).
1229
1327
  skills: [],
1230
1328
  }));
1329
+ // A session that is ALREADY live -- a brand-new session (session_new) or
1330
+ // a warm attach -- has its agent (and resource loader) right now, but a
1331
+ // brand-new session never emits session_ready, so waiting for that alone
1332
+ // left `/skill:` autocomplete empty on a fresh session. Request the list
1333
+ // here whenever the agent is not pending; re-requesting is safe (the
1334
+ // server always replies with the full list).
1335
+ if (msg.pending !== true && msg.sessionId) {
1336
+ this.send({type: 'skills_request', sessionId: msg.sessionId});
1337
+ }
1231
1338
  break;
1232
1339
  }
1233
1340
 
@@ -1256,6 +1363,17 @@ export class WhereverClient {
1256
1363
  }
1257
1364
  break;
1258
1365
 
1366
+ case 'session_reloading':
1367
+ // A `/reload` was accepted (by us or another viewer): the live agent is
1368
+ // being rebuilt. Block the composer exactly like a cold load; the
1369
+ // session_ready (or session_error) that ends the reload clears it and
1370
+ // re-requests the skill list. Ignore a frame for a session we left.
1371
+ this.stateStore.update((s: WhereverState) => {
1372
+ if (s.sessionId && msg.sessionId && s.sessionId !== msg.sessionId) return s;
1373
+ return { ...s, agentPending: true };
1374
+ });
1375
+ break;
1376
+
1259
1377
  case 'skills_list':
1260
1378
  // The set of `/skill:<name>` commands for the active session. Replace
1261
1379
  // outright; ignore a list for a session we already switched away from.
@@ -1313,6 +1431,8 @@ export class WhereverClient {
1313
1431
  activeModel: null,
1314
1432
  loadingSession: false,
1315
1433
  agentPending: false,
1434
+ folderMissing: null,
1435
+ restore: null,
1316
1436
  notice: null,
1317
1437
  sudoPrompt: null,
1318
1438
  };
@@ -1336,6 +1456,126 @@ export class WhereverClient {
1336
1456
  }));
1337
1457
  break;
1338
1458
 
1459
+ case 'folder_missing':
1460
+ // The server states, authoritatively, that this session's working folder
1461
+ // is not usable -- it does not exist on this machine, or a restore is
1462
+ // still materialising it -- and names the absolute path. No session_ready
1463
+ // is coming (no agent was built), so this is also the end of the load:
1464
+ // read-only, with an explanation. Ignore a frame for a session we already
1465
+ // switched away from.
1466
+ //
1467
+ // `job` is any restore the server is ALREADY running for that path, so a
1468
+ // reconnect or a second device paints the running clone from this one
1469
+ // frame. With no job the panel simply offers to start one; either way the
1470
+ // restore state exists from here on, so a job another device starts is
1471
+ // painted by the progress frames that follow.
1472
+ this.stateStore.update((s: WhereverState) => {
1473
+ if (s.sessionId && msg.sessionId && s.sessionId !== msg.sessionId) return s;
1474
+ return {
1475
+ ...s,
1476
+ readOnly: true,
1477
+ folderMissing: {cwd: msg.cwd},
1478
+ restore: {
1479
+ targetPath: msg.cwd,
1480
+ job: (msg.job as RestoreJobInfo | undefined) ?? null,
1481
+ joined: false,
1482
+ rejection: null,
1483
+ },
1484
+ };
1485
+ });
1486
+ break;
1487
+
1488
+ case 'restore_started': {
1489
+ // The answer to OUR restore_start. `outcome: 'joined'` means a job was
1490
+ // already running for this path and we coalesced onto it, so `job.url` is
1491
+ // the url really in flight -- which the panel must show when it differs
1492
+ // from the one this client asked for, rather than pretending the edited
1493
+ // url was accepted.
1494
+ //
1495
+ // It is ALSO the answer to a `session_new` that chose to CLONE an
1496
+ // existing remote. That create has no restore state yet (no session, so
1497
+ // no folder-missing frame ever created one), so the job is ADOPTED here
1498
+ // as the create's own: the blocking "Creating session..." overlay gives
1499
+ // way to the same progress the restore panel renders, and the create
1500
+ // watchdog -- which fires long before a large repository finishes -- is
1501
+ // disarmed, because a watched job is no longer something to time out.
1502
+ const before = get(this.stateStore);
1503
+ if (before.creatingSession && !before.restore) {
1504
+ this.clearCreateWatchdog();
1505
+ this.stateStore.update((s: WhereverState) => ({
1506
+ ...s,
1507
+ creatingSession: false,
1508
+ restore: {
1509
+ targetPath: msg.targetPath,
1510
+ job: msg.job as RestoreJobInfo,
1511
+ joined: msg.outcome === 'joined',
1512
+ rejection: null,
1513
+ forSessionCreate: true,
1514
+ },
1515
+ }));
1516
+ break;
1517
+ }
1518
+ this.stateStore.update((s: WhereverState) =>
1519
+ this.withRestore(s, msg.targetPath, (r) => ({
1520
+ ...r,
1521
+ job: msg.job as RestoreJobInfo,
1522
+ joined: msg.outcome === 'joined',
1523
+ rejection: null,
1524
+ })),
1525
+ );
1526
+ break;
1527
+ }
1528
+
1529
+ case 'restore_rejected':
1530
+ // Refused before anything was spawned: no job, no completion coming. Keep
1531
+ // whatever job state we had (a rejection answers OUR request, it does not
1532
+ // touch a job someone else is running) and surface the reason.
1533
+ this.stateStore.update((s: WhereverState) =>
1534
+ this.withRestore(s, msg.targetPath, (r) => ({
1535
+ ...r,
1536
+ rejection: {reason: msg.reason, message: msg.message},
1537
+ })),
1538
+ );
1539
+ break;
1540
+
1541
+ case 'restore_progress':
1542
+ case 'restore_complete': {
1543
+ // Broadcast frames: the server sends them to every client whose folder
1544
+ // matches the job path, so they arrive whether or not THIS client started
1545
+ // the restore (a second device, or a reconnect mid-clone). Each carries
1546
+ // the whole job snapshot, so one frame is enough to repaint.
1547
+ //
1548
+ // The new-session clone ends differently from the panel's: there is
1549
+ // nothing to reload, so a job that SUCCEEDED hands the screen straight
1550
+ // back to the create the server is already continuing with (overlay +
1551
+ // watchdog re-armed for that last, ordinary step). A failed or cancelled
1552
+ // one ends the create; the server's session_error, carrying the mapped
1553
+ // cause, arrives beside this frame.
1554
+ const current = get(this.stateStore).restore;
1555
+ if (
1556
+ msg.type === 'restore_complete' &&
1557
+ current?.forSessionCreate &&
1558
+ current.targetPath === msg.targetPath
1559
+ ) {
1560
+ const cloned = (msg.job as RestoreJobInfo).state === 'done';
1561
+ this.stateStore.update((s: WhereverState) => ({
1562
+ ...s,
1563
+ restore: null,
1564
+ creatingSession: cloned,
1565
+ }));
1566
+ if (cloned) this.armCreateWatchdog();
1567
+ break;
1568
+ }
1569
+ this.stateStore.update((s: WhereverState) =>
1570
+ this.withRestore(s, msg.targetPath, (r) => ({
1571
+ ...r,
1572
+ job: msg.job as RestoreJobInfo,
1573
+ rejection: null,
1574
+ })),
1575
+ );
1576
+ break;
1577
+ }
1578
+
1339
1579
  case 'folder_conflict':
1340
1580
  // Live update of whether another active session still exists in this
1341
1581
  // client's folder. The banner appears when a second session shows up in
@@ -1344,15 +1584,25 @@ export class WhereverClient {
1344
1584
  this.stateStore.update((s: WhereverState) => {
1345
1585
  if (!s.sessionId) return s;
1346
1586
  if (s.activeCwd && msg.cwd !== s.activeCwd) return s;
1587
+ // The server re-evaluates this client's read-only state on every
1588
+ // conflict update, so mirror it when reported. This is what releases
1589
+ // the composer once the conflict resolves (the banner alone cannot: it
1590
+ // disappears, taking its "Continue anyway" button with it) and what
1591
+ // keeps a hard sessions.readOnly folder locked. Older servers omit the
1592
+ // field, leaving read-only untouched as before.
1593
+ const readOnly = msg.readOnly ?? s.readOnly;
1347
1594
  if (!msg.active) {
1348
1595
  // No other session remains: fully resolved, drop the banner.
1349
- return s.folderConflict ? {...s, folderConflict: null} : s;
1596
+ return s.folderConflict || readOnly !== s.readOnly
1597
+ ? {...s, folderConflict: null, readOnly}
1598
+ : s;
1350
1599
  }
1351
1600
  if (s.folderConflict) {
1352
1601
  // Already showing: just refresh, preserving the user's `continued`
1353
1602
  // choice (so we don't re-disable a composer they already enabled).
1354
1603
  return {
1355
1604
  ...s,
1605
+ readOnly,
1356
1606
  folderConflict: {...s.folderConflict, cwd: msg.cwd, active: true},
1357
1607
  };
1358
1608
  }
@@ -1362,6 +1612,7 @@ export class WhereverClient {
1362
1612
  // than yanking the composer into read-only underneath the user.
1363
1613
  return {
1364
1614
  ...s,
1615
+ readOnly,
1365
1616
  folderConflict: {cwd: msg.cwd, active: true, continued: true},
1366
1617
  };
1367
1618
  });
@@ -1868,6 +2119,52 @@ export class WhereverClient {
1868
2119
  return true;
1869
2120
  }
1870
2121
 
2122
+ // Re-materialize queued steers the message list does not have. A queued
2123
+ // message lives ONLY in the agent's memory until pi injects it at the next
2124
+ // step: it is not in the session file, so message_history cannot contain it.
2125
+ // On attach (a reload, or a second device) the server sends the queue as a
2126
+ // snapshot; without this the text would be invisible until it was delivered,
2127
+ // even though it was still going to be sent. Any queued entry with no matching
2128
+ // user message is appended so the UI can render it with the "Queued" badge and
2129
+ // the session-level cancel.
2130
+ //
2131
+ // Matching is by CONTENT, because the queue is a list of strings (pi exposes
2132
+ // no per-entry id). Occurrences are COUNTED, so a text queued twice restores
2133
+ // two bubbles, and a locally-sent (optimistic) steer already on screen is not
2134
+ // duplicated by the snapshot that follows it.
2135
+ private withRestoredQueuedMessages(
2136
+ messages: ChatMessage[],
2137
+ steering: string[],
2138
+ ): ChatMessage[] {
2139
+ if (steering.length === 0) return messages;
2140
+ const have = new Map<string, number>();
2141
+ for (const m of messages) {
2142
+ if (m.role !== 'user') continue;
2143
+ have.set(m.content, (have.get(m.content) ?? 0) + 1);
2144
+ }
2145
+ const restored: ChatMessage[] = [];
2146
+ for (const text of steering) {
2147
+ const remaining = have.get(text) ?? 0;
2148
+ if (remaining > 0) {
2149
+ have.set(text, remaining - 1);
2150
+ continue;
2151
+ }
2152
+ restored.push({
2153
+ id: this.generateId(),
2154
+ role: 'user',
2155
+ content: text,
2156
+ timestamp: Date.now(),
2157
+ isStreaming: false,
2158
+ restoredFromQueue: true,
2159
+ // NOT delivery-tracked: the server already holds this message, so it is
2160
+ // delivered as far as we are concerned. Tagging it pending would arm a
2161
+ // confirmation watchdog and wrongly offer "Retry" for a message that is
2162
+ // queued and will be sent.
2163
+ });
2164
+ }
2165
+ return restored.length > 0 ? [...messages, ...restored] : messages;
2166
+ }
2167
+
1871
2168
  // ==========================================================================
1872
2169
  // Outbound-message delivery confirmation + recovery.
1873
2170
  //
@@ -2078,6 +2375,17 @@ export class WhereverClient {
2078
2375
  this.send({type: 'abort', sessionId: s.sessionId});
2079
2376
  }
2080
2377
 
2378
+ // The web `/reload`: ask the server to rebuild the active session's agent so
2379
+ // it re-reads settings, extensions, skills, prompts and context files. Nothing
2380
+ // is changed locally: the server answers session_reloading (block the
2381
+ // composer), then session_ready, or a session_notice when it refuses (the
2382
+ // agent is busy, a CLI bridge owns the session, read-only).
2383
+ public reloadResources(): void {
2384
+ const s = get(this.stateStore);
2385
+ if (!s.sessionId) return;
2386
+ this.send({type: 'session_reload', sessionId: s.sessionId});
2387
+ }
2388
+
2081
2389
  // Cancel the queued mid-stream steer messages for the active session without
2082
2390
  // aborting the in-flight turn. Optimistically clears our local pending-steer
2083
2391
  // set so the "Cancel" affordance disappears immediately; the server's fresh
@@ -2089,10 +2397,32 @@ export class WhereverClient {
2089
2397
  this.stateStore.update((st: WhereverState) => ({...st, pendingSteering: []}));
2090
2398
  }
2091
2399
 
2400
+ /**
2401
+ * Apply `mutate` to the restore state for `targetPath`, or ignore the frame.
2402
+ *
2403
+ * Restore frames are addressed by PATH (the server's job key) rather than by
2404
+ * session id, because the server derives who gets them from a path match. This
2405
+ * is where a frame for a folder this client is no longer looking at is dropped
2406
+ * -- the one still in flight when the user switched sessions.
2407
+ */
2408
+ private withRestore(
2409
+ s: WhereverState,
2410
+ targetPath: string,
2411
+ mutate: (restore: RestoreInfo) => RestoreInfo,
2412
+ ): WhereverState {
2413
+ const current = s.restore;
2414
+ if (!current || current.targetPath !== targetPath) return s;
2415
+ return {...s, restore: mutate(current)};
2416
+ }
2417
+
2092
2418
  public joinSession(sessionFile: string, cwd?: string, model?: string) {
2093
2419
  this.stateStore.update((s: WhereverState) => ({
2094
2420
  ...s,
2095
2421
  folderConflict: null,
2422
+ // Both folder verdicts belong to the session being left; the load we are
2423
+ // starting re-states its own (the server re-checks on every load).
2424
+ folderMissing: null,
2425
+ restore: null,
2096
2426
  sessionError: null,
2097
2427
  loadingSession: true,
2098
2428
  agentPending: false,
@@ -2132,6 +2462,8 @@ export class WhereverClient {
2132
2462
  activeModel: null,
2133
2463
  readOnly: false,
2134
2464
  folderConflict: null,
2465
+ folderMissing: null,
2466
+ restore: null,
2135
2467
  sessionError: null,
2136
2468
  notice: null,
2137
2469
  sudoPrompt: null,
@@ -2175,6 +2507,10 @@ export class WhereverClient {
2175
2507
  this.stateStore.update((s: WhereverState) => ({
2176
2508
  ...s,
2177
2509
  folderConflict: null,
2510
+ // Creating a session creates its folder, so no missing-folder lock can
2511
+ // survive into it.
2512
+ folderMissing: null,
2513
+ restore: null,
2178
2514
  sessionError: null,
2179
2515
  creatingSession: true,
2180
2516
  loadingSession: false,
@@ -2221,6 +2557,8 @@ export class WhereverClient {
2221
2557
  activeCwd: null,
2222
2558
  activeModel: null,
2223
2559
  readOnly: false,
2560
+ folderMissing: null,
2561
+ restore: null,
2224
2562
  notice: null,
2225
2563
  sudoPrompt: null,
2226
2564
  creatingSession: false,
@@ -2237,6 +2575,88 @@ export class WhereverClient {
2237
2575
  this.resumeModel = undefined;
2238
2576
  }
2239
2577
 
2578
+ // --- RESTORE: materialise the active session's missing working folder -----
2579
+ //
2580
+ // "Restore" here means making the missing FOLDER exist again (clone it back,
2581
+ // or create it), never the unrelated re-materialising of queued steers/drafts
2582
+ // after a reload. See CONTEXT.md; the whole family is namespaced `restore*`.
2583
+
2584
+ /**
2585
+ * Ask the server to restore the folder of the folder-missing session this
2586
+ * client is looking at: CLONE `url` into it, or CREATE it.
2587
+ *
2588
+ * The job is server-owned and keyed by that path, so this may well JOIN a job
2589
+ * another device (or this client's previous, dropped socket) already started;
2590
+ * the server's `restore_started` says which, and carries the url really in
2591
+ * flight. Returns false when there is no missing folder to restore, or when a
2592
+ * clone was asked for with no url.
2593
+ */
2594
+ public startRestore(
2595
+ action: 'clone' | 'create',
2596
+ url?: string,
2597
+ gitInit?: boolean,
2598
+ ): boolean {
2599
+ const s = get(this.stateStore);
2600
+ const targetPath = s.restore?.targetPath ?? s.folderMissing?.cwd;
2601
+ if (!targetPath) return false;
2602
+ const trimmedUrl = url?.trim();
2603
+ if (action === 'clone' && !trimmedUrl) return false;
2604
+ // Record what WE asked for before the answer lands, so the panel can compare
2605
+ // it with the url the (possibly joined) job is really cloning.
2606
+ this.stateStore.update((st: WhereverState) => {
2607
+ const previous = st.restore?.targetPath === targetPath ? st.restore.job : null;
2608
+ return {
2609
+ ...st,
2610
+ restore: {
2611
+ targetPath,
2612
+ // A RUNNING job is the one this request will join, so it stays on
2613
+ // screen. A terminal one belonged to the attempt being retried: drop
2614
+ // it, so the panel shows this request in flight rather than the
2615
+ // previous failure until the server answers.
2616
+ job: previous && previous.state === 'running' ? previous : null,
2617
+ joined: false,
2618
+ requestedUrl: trimmedUrl,
2619
+ rejection: null,
2620
+ },
2621
+ };
2622
+ });
2623
+ return this.send({
2624
+ type: 'restore_start',
2625
+ targetPath,
2626
+ action,
2627
+ ...(trimmedUrl ? {url: trimmedUrl} : {}),
2628
+ ...(gitInit !== undefined ? {gitInit} : {}),
2629
+ });
2630
+ }
2631
+
2632
+ /**
2633
+ * Cancel the restore running for this session's folder. The server settles the
2634
+ * job authoritatively and broadcasts the `cancelled` completion to every client
2635
+ * watching that folder (this one included), so no state is guessed here.
2636
+ */
2637
+ public cancelRestore(): boolean {
2638
+ const s = get(this.stateStore);
2639
+ const targetPath = s.restore?.targetPath;
2640
+ if (!targetPath) return false;
2641
+ return this.send({type: 'restore_cancel', targetPath});
2642
+ }
2643
+
2644
+ /**
2645
+ * Re-load the active session file.
2646
+ *
2647
+ * This is how a completed restore goes LIVE: whether a session has a live agent
2648
+ * is a load-time decision, and the load that found the folder missing
2649
+ * deliberately built none. Re-loading is therefore the honest way to get one,
2650
+ * not a refresh hint. Returns false when there is no active session file.
2651
+ */
2652
+ public reloadSession(): boolean {
2653
+ const s = get(this.stateStore);
2654
+ const sessionFile = s.activeSessionFile;
2655
+ if (!sessionFile) return false;
2656
+ this.joinSession(sessionFile, s.activeCwd ?? undefined);
2657
+ return true;
2658
+ }
2659
+
2240
2660
  // "Continue anyway" on the folder-conflict warning banner: ask the server to
2241
2661
  // lift read-only for this client's current session (both sessions in the
2242
2662
  // folder then run concurrently; the other is NOT aborted). Optimistically
@@ -2245,6 +2665,10 @@ export class WhereverClient {
2245
2665
  public continueFolderConflict() {
2246
2666
  const s = get(this.stateStore);
2247
2667
  if (!s.folderConflict || !s.sessionId) return;
2668
+ // "Continue anyway" answers a folder CONFLICT only. A missing folder is a
2669
+ // hard lock (there is nothing to drive, and no agent was built), and the
2670
+ // server refuses to lift it, so do not flash an enabled composer here.
2671
+ if (s.folderMissing) return;
2248
2672
 
2249
2673
  this.send({
2250
2674
  type: 'folder_conflict_continue',