wherever-dev 0.18.4 → 0.19.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.
Files changed (61) hide show
  1. package/dist/builtin-extensions.d.ts +28 -0
  2. package/dist/builtin-extensions.d.ts.map +1 -0
  3. package/dist/builtin-extensions.js +28 -0
  4. package/dist/builtin-extensions.js.map +1 -0
  5. package/dist/config-dir.d.ts +13 -0
  6. package/dist/config-dir.d.ts.map +1 -0
  7. package/dist/config-dir.js +18 -0
  8. package/dist/config-dir.js.map +1 -0
  9. package/dist/extension-lifecycle.d.ts +3 -2
  10. package/dist/extension-lifecycle.d.ts.map +1 -1
  11. package/dist/extension-lifecycle.js +8 -4
  12. package/dist/extension-lifecycle.js.map +1 -1
  13. package/dist/index.js +377 -35
  14. package/dist/index.js.map +1 -1
  15. package/dist/pi-sdk-policy.d.ts +91 -0
  16. package/dist/pi-sdk-policy.d.ts.map +1 -0
  17. package/dist/pi-sdk-policy.js +173 -0
  18. package/dist/pi-sdk-policy.js.map +1 -0
  19. package/dist/pi-sdk.d.ts +56 -0
  20. package/dist/pi-sdk.d.ts.map +1 -0
  21. package/dist/pi-sdk.js +124 -0
  22. package/dist/pi-sdk.js.map +1 -0
  23. package/dist/protocol.d.ts +23 -0
  24. package/dist/protocol.d.ts.map +1 -1
  25. package/dist/session-pool.d.ts +56 -12
  26. package/dist/session-pool.d.ts.map +1 -1
  27. package/dist/session-pool.js +108 -36
  28. package/dist/session-pool.js.map +1 -1
  29. package/dist/upload-gate.d.ts +96 -0
  30. package/dist/upload-gate.d.ts.map +1 -0
  31. package/dist/upload-gate.js +109 -0
  32. package/dist/upload-gate.js.map +1 -0
  33. package/dist/upload-staging.d.ts +172 -0
  34. package/dist/upload-staging.d.ts.map +1 -0
  35. package/dist/upload-staging.js +368 -0
  36. package/dist/upload-staging.js.map +1 -0
  37. package/package.json +5 -3
  38. package/public/_app/immutable/assets/{0.BnOlDJL_.css → 0.Cb5vRzMp.css} +1 -1
  39. package/public/_app/immutable/chunks/{wEbpki5g.js → B4u7MCsa.js} +2 -2
  40. package/public/_app/immutable/chunks/{wEbpki5g.js.map → B4u7MCsa.js.map} +1 -1
  41. package/public/_app/immutable/chunks/{D7qz2w2U.js → CMMpRRWm.js} +2 -2
  42. package/public/_app/immutable/chunks/{D7qz2w2U.js.map → CMMpRRWm.js.map} +1 -1
  43. package/public/_app/immutable/chunks/{Ds-VJGnt.js → D7cniAcl.js} +2 -2
  44. package/public/_app/immutable/chunks/{Ds-VJGnt.js.map → D7cniAcl.js.map} +1 -1
  45. package/public/_app/immutable/entry/{app.DTMeXTQG.js → app.B09hP3rk.js} +3 -3
  46. package/public/_app/immutable/entry/{app.DTMeXTQG.js.map → app.B09hP3rk.js.map} +1 -1
  47. package/public/_app/immutable/entry/start.DsunIvKH.js +2 -0
  48. package/public/_app/immutable/entry/start.DsunIvKH.js.map +1 -0
  49. package/public/_app/immutable/nodes/{0.CCTuxjIi.js → 0.Bl6oKVU5.js} +2 -2
  50. package/public/_app/immutable/nodes/{0.CCTuxjIi.js.map → 0.Bl6oKVU5.js.map} +1 -1
  51. package/public/_app/immutable/nodes/{1.5ZhRu6ko.js → 1.H6kc-Qsz.js} +2 -2
  52. package/public/_app/immutable/nodes/{1.5ZhRu6ko.js.map → 1.H6kc-Qsz.js.map} +1 -1
  53. package/public/_app/immutable/nodes/2.B6sChdvF.js +120 -0
  54. package/public/_app/immutable/nodes/2.B6sChdvF.js.map +1 -0
  55. package/public/_app/version.json +1 -1
  56. package/public/index.html +11 -11
  57. package/public/service-worker.js +1 -1
  58. package/public/_app/immutable/entry/start.CwhL7q0v.js +0 -2
  59. package/public/_app/immutable/entry/start.CwhL7q0v.js.map +0 -1
  60. package/public/_app/immutable/nodes/2.DOUZvKq4.js +0 -120
  61. package/public/_app/immutable/nodes/2.DOUZvKq4.js.map +0 -1
package/dist/index.js CHANGED
@@ -3,12 +3,15 @@ import { createServer as createHttpServer } from 'node:http';
3
3
  import { createServer as createHttpsServer, request as httpRequest } from 'node:https';
4
4
  import { connect as netConnect } from 'node:net';
5
5
  import { WebSocketServer, WebSocket } from 'ws';
6
- import { SessionPool, RELOADING_REFUSAL, getWhereverConfig, getWhereverCertsDir, detectRemoteRepo, normalizePath, invalidateFolderExistence } from './session-pool.js';
6
+ import { SessionPool, RELOADING_REFUSAL, getWhereverConfig, getWhereverCertsDir, getWhereverStateDir, detectRemoteRepo, normalizePath, invalidateFolderExistence } from './session-pool.js';
7
7
  import { readDrafts, addDraft, deleteDraft, validateDraftInput } from './drafts.js';
8
+ import { piSdkInfo } from './pi-sdk.js';
8
9
  import { searchConversations } from './conversation-search.js';
9
10
  import { matchRemoteRepoRule, resolveRemoteCandidates } from './remote-candidates.js';
10
11
  import { RestoreJobRegistry } from './restore-jobs.js';
11
12
  import { INITIAL_HISTORY_LIMIT, HISTORY_PAGE_SIZE } from './protocol.js';
13
+ import { gateUploadFolder, gateUploadWrite, uploadMaxBytes, uploadTooLarge } from './upload-gate.js';
14
+ import { UploadStaging, UPLOAD_CAPABILITY, isValidUploadId, parseChunkFrame, CHUNK_FRAME_KIND } from './upload-staging.js';
12
15
  import fs from 'node:fs';
13
16
  import path from 'node:path';
14
17
  import { fileURLToPath } from 'node:url';
@@ -175,7 +178,17 @@ function resolveDownloadRoots(config, cwd) {
175
178
  add(resolveUploadDir(config, cwd));
176
179
  for (const r of config.downloads?.roots || [])
177
180
  add(r);
178
- return Array.from(roots);
181
+ // The upload staging dir holds PARTIAL uploads and is never a download root,
182
+ // whatever the config says (docs/adr/0012).
183
+ const staging = getUploadStaging();
184
+ return Array.from(roots).filter((r) => !staging.contains(r));
185
+ }
186
+ let uploadStaging;
187
+ /** The one staging area for chunked uploads: `<state dir>/upload-staging` (created lazily). */
188
+ function getUploadStaging() {
189
+ if (!uploadStaging)
190
+ uploadStaging = new UploadStaging({ dir: path.join(getWhereverStateDir(), 'upload-staging') });
191
+ return uploadStaging;
179
192
  }
180
193
  /**
181
194
  * Validate a requested download path against the allowed roots and return the
@@ -212,6 +225,10 @@ function resolveSafeDownloadPath(requested, cwd, roots) {
212
225
  }
213
226
  if (!stat.isFile())
214
227
  return null; // never serve directories/devices
228
+ // Partial uploads are never downloadable, even when a root (a session cwd at
229
+ // the state dir's parent, a configured root) happens to contain the staging dir.
230
+ if (getUploadStaging().contains(real))
231
+ return null;
215
232
  const withinRoot = roots.some((root) => {
216
233
  if (real === root)
217
234
  return true;
@@ -267,6 +284,30 @@ function serveStaticFile(reqPath, res) {
267
284
  }
268
285
  });
269
286
  }
287
+ const DEFAULT_HEARTBEAT_MS = 30_000;
288
+ /**
289
+ * Resolve the WebSocket heartbeat interval from `WHEREVER_HEARTBEAT_MS`.
290
+ *
291
+ * Decision: an unset or empty value keeps the 30 000 ms default; a value that
292
+ * is not a positive integer (e.g. `abc`, `0`, `-5`, `1.5`) is IGNORED with a
293
+ * startup warning and the default is used, rather than refusing to start. The
294
+ * variable exists mainly so tests can shorten the interval, so a typo should
295
+ * not take a production server down; the alternative (fail fast at startup)
296
+ * was considered and rejected for that reason. Touches nothing else: no CLI
297
+ * flag or config.json key mirrors it.
298
+ */
299
+ function resolveHeartbeatMs(raw) {
300
+ if (raw == null || raw.trim() === '')
301
+ return DEFAULT_HEARTBEAT_MS;
302
+ const trimmed = raw.trim();
303
+ const n = Number(trimmed);
304
+ if (!/^\d+$/.test(trimmed) || !Number.isSafeInteger(n) || n <= 0) {
305
+ console.warn(`[wherever] ignoring invalid WHEREVER_HEARTBEAT_MS=${JSON.stringify(raw)} ` +
306
+ `(expected a positive integer of milliseconds); using ${DEFAULT_HEARTBEAT_MS}`);
307
+ return DEFAULT_HEARTBEAT_MS;
308
+ }
309
+ return n;
310
+ }
270
311
  // Retire any still-registered VIEWER connection carrying the same clientKey: it
271
312
  // is the SAME viewer's superseded socket (a reconnect), not a second viewer.
272
313
  // Detach it from its session synchronously so the very next message on the new
@@ -757,6 +798,17 @@ function resolveUploadDir(config, cwd) {
757
798
  // Default to tmp
758
799
  return os.tmpdir();
759
800
  }
801
+ /**
802
+ * Answer an upload refusal while the client may still be sending its body: the
803
+ * reply carries `Connection: close` and the rest of the body is drained rather
804
+ * than parsed, so the client reads the reason instead of a reset mid-send, and a
805
+ * huge refused body is not buffered.
806
+ */
807
+ function refuseUpload(req, res, status, error) {
808
+ res.writeHead(status, { 'Content-Type': 'application/json', Connection: 'close' });
809
+ res.end(JSON.stringify({ error }));
810
+ req.resume();
811
+ }
760
812
  function sendJSON(res, status, data) {
761
813
  res.writeHead(status, { 'Content-Type': 'application/json' });
762
814
  res.end(JSON.stringify(data));
@@ -828,8 +880,23 @@ function sendThenTerminate(ws, msg, flushTimeoutMs = 1_000) {
828
880
  async function main() {
829
881
  const { port, host, socket, token, tokenSource, idleTimeout, sslKey, sslCert, noSsl, httpLocalhostFallbackPort, debug } = parseArgs();
830
882
  debugEnabled = debug;
883
+ console.log(`[wherever] pi SDK ${piSdkInfo.version}: ` +
884
+ (piSdkInfo.tier === 'bundled' ? `bundled (${piSdkInfo.why})` : `${piSdkInfo.tier}, from ${piSdkInfo.root} (${piSdkInfo.why})`));
831
885
  const sessionPool = new SessionPool(idleTimeout);
832
886
  await sessionPool.initialize();
887
+ // Abandoned partial uploads (untouched for 24 h) are collected at startup and
888
+ // then hourly. A no-op when the staging dir was never created. The startup
889
+ // pass is awaited (one readdir) so it is done before the first upload arrives.
890
+ const runUploadGc = () => getUploadStaging()
891
+ .gc()
892
+ .then((n) => {
893
+ if (n > 0)
894
+ console.log(`[wherever] removed ${n} stale upload staging entr${n === 1 ? 'y' : 'ies'}`);
895
+ })
896
+ .catch((err) => console.warn('[wherever] upload staging GC failed:', err.message));
897
+ await runUploadGc();
898
+ const uploadGcTimer = setInterval(runUploadGc, 60 * 60 * 1000);
899
+ uploadGcTimer.unref?.();
833
900
  const clients = new Map();
834
901
  // expandTilde so `~/certs/...` works from a systemd `Environment=` line or an
835
902
  // EnvironmentFile, neither of which is shell-expanded. Without it the read
@@ -1213,7 +1280,7 @@ async function main() {
1213
1280
  return;
1214
1281
  }
1215
1282
  if (pathname === '/models' && req.method === 'GET') {
1216
- const models = sessionPool.getAvailableModels();
1283
+ const models = await sessionPool.getAvailableModels();
1217
1284
  sendJSON(res, 200, { models });
1218
1285
  return;
1219
1286
  }
@@ -1297,7 +1364,7 @@ async function main() {
1297
1364
  // (folder-local harness/pi config wins), so the search composer can seed its
1298
1365
  // model picker with the folder default rather than the server global.
1299
1366
  const searchDefaultModel = searchFolder
1300
- ? sessionPool.getDefaultModelFor(searchFolder)
1367
+ ? await sessionPool.getDefaultModelFor(searchFolder)
1301
1368
  : null;
1302
1369
  // The label defaults to the machine hostname so two servers sharing the
1303
1370
  // same sessions over cloned folders are distinguishable with zero config.
@@ -1756,26 +1823,88 @@ async function main() {
1756
1823
  sendJSON(res, 400, { error: 'Missing sessionId or filename' });
1757
1824
  return;
1758
1825
  }
1759
- const tracked = sessionPool.getSession(qSessionId);
1760
- const cwd = tracked?.cwd;
1826
+ // The session's folder, from the pool when it is loaded, else from the
1827
+ // session file's HEADER: the composer stays editable while a cold agent
1828
+ // builds, so a not-yet-loaded session must be accepted (and must not fall
1829
+ // back to tmp, which `pool.getSession()` alone used to do). Only a
1830
+ // session that cannot be resolved at all is a 404.
1831
+ const meta = await sessionPool.readSessionFolderMeta(qSessionId);
1832
+ if ('error' in meta) {
1833
+ refuseUpload(req, res, 404, meta.error);
1834
+ return;
1835
+ }
1836
+ // The hard read-only reasons (gateUploadFolder). The per-viewer
1837
+ // folder-conflict lock is a socket's state, which a POST does not have.
1838
+ const gate = gateUploadFolder({
1839
+ cwd: meta.cwd,
1840
+ readOnly: meta.readOnly,
1841
+ folderMissing: meta.folderMissing,
1842
+ restoring: restoreJobs.get(meta.cwd)?.state === 'running',
1843
+ });
1844
+ if (!gate.ok) {
1845
+ refuseUpload(req, res, 403, gate.reason);
1846
+ return;
1847
+ }
1761
1848
  const config = getWhereverConfig();
1762
- const targetDir = resolveUploadDir(config, cwd);
1849
+ const maxBytes = uploadMaxBytes(config);
1850
+ const declared = Number(req.headers['content-length']);
1851
+ if (Number.isFinite(declared)) {
1852
+ const tooLarge = uploadTooLarge(declared, maxBytes);
1853
+ if (tooLarge) {
1854
+ refuseUpload(req, res, 413, tooLarge);
1855
+ return;
1856
+ }
1857
+ }
1858
+ const targetDir = resolveUploadDir(config, gate.cwd);
1763
1859
  fs.mkdirSync(targetDir, { recursive: true });
1764
1860
  const timestamp = Date.now();
1765
1861
  const safeFilename = `${timestamp}_${path.basename(qFilename)}`;
1766
1862
  const destPath = path.join(targetDir, safeFilename);
1767
1863
  const writeStream = fs.createWriteStream(destPath);
1864
+ // Settle exactly once. Every failure path destroys the write stream and
1865
+ // unlinks the partial file BEFORE answering, so a refused or broken
1866
+ // upload never leaves a truncated file in the upload dir.
1867
+ let settled = false;
1868
+ const fail = (status, error) => {
1869
+ if (settled)
1870
+ return;
1871
+ settled = true;
1872
+ req.unpipe(writeStream);
1873
+ writeStream.destroy();
1874
+ const answer = () => {
1875
+ fs.promises.unlink(destPath).catch(() => { }).finally(() => {
1876
+ if (!res.headersSent && !res.destroyed)
1877
+ refuseUpload(req, res, status, error);
1878
+ });
1879
+ };
1880
+ if (writeStream.closed)
1881
+ answer();
1882
+ else
1883
+ writeStream.once('close', answer);
1884
+ };
1885
+ // A running count, for a body without Content-Length (chunked), which
1886
+ // the header check above cannot see.
1887
+ let received = 0;
1888
+ req.on('data', (chunk) => {
1889
+ received += chunk.length;
1890
+ const tooLarge = uploadTooLarge(received, maxBytes);
1891
+ if (tooLarge)
1892
+ fail(413, tooLarge);
1893
+ });
1894
+ req.on('aborted', () => fail(400, 'Upload aborted by the client'));
1895
+ req.on('error', (err) => fail(400, `Upload failed: ${err.message}`));
1768
1896
  req.pipe(writeStream);
1769
1897
  writeStream.on('finish', () => {
1898
+ if (settled)
1899
+ return;
1900
+ settled = true;
1770
1901
  sendJSON(res, 200, {
1771
1902
  status: 'uploaded',
1772
1903
  filename: qFilename,
1773
1904
  savedPath: destPath
1774
1905
  });
1775
1906
  });
1776
- writeStream.on('error', (err) => {
1777
- sendJSON(res, 500, { error: `Failed to write file: ${err.message}` });
1778
- });
1907
+ writeStream.on('error', (err) => fail(500, `Failed to write file: ${err.message}`));
1779
1908
  }
1780
1909
  catch (err) {
1781
1910
  sendJSON(res, 500, { error: `Upload error: ${err.message}` });
@@ -1993,12 +2122,27 @@ async function main() {
1993
2122
  // a clean FIN/RST: process restart, network blip, dropped upstream) stays in
1994
2123
  // ESTAB and fires neither 'close' nor 'error', so the connected agent/session
1995
2124
  // is never reaped and hangs forever. We send a protocol-level ping frame on a
1996
- // fixed interval and terminate any socket that did not answer the previous
1997
- // ping. terminate() fires 'close', routing through the existing cleanup
1998
- // (unregisterCliSession / removeClient + broadcastSessionsUpdated).
2125
+ // fixed interval and terminate any socket that stayed silent for
2126
+ // HEARTBEAT_MAX_MISSES consecutive pings. terminate() fires 'close', routing
2127
+ // through the existing cleanup (unregisterCliSession / removeClient +
2128
+ // broadcastSessionsUpdated).
1999
2129
  // See work/observations/ws-half-open-connection-hangs-agent-no-heartbeat.md.
2000
- const HEARTBEAT_MS = 30_000;
2001
- const liveSockets = new WeakSet();
2130
+ //
2131
+ // Why N=2 and not 1 (ADR 0011): the primary client is a phone on a flaky
2132
+ // link, where a single late pong is routine; reaping on it turned a healthy
2133
+ // socket into a reconnect + resync. And ANY inbound message (text or binary)
2134
+ // counts as proof of life exactly like a pong, because a client busily
2135
+ // sending (e.g. chunked upload frames) can have its pong queued behind that
2136
+ // data on the same TCP stream. Trade-off: a genuinely dead socket is reaped
2137
+ // one interval later than before, so a vanished viewer can count as present
2138
+ // for up to ~3x HEARTBEAT_MS (up to one interval until the first unanswered
2139
+ // ping, plus two missed intervals). Same-tab reconnects are unaffected: they
2140
+ // are evicted immediately by clientKey (evictPreviousConnection).
2141
+ const HEARTBEAT_MAX_MISSES = 2;
2142
+ const HEARTBEAT_MS = resolveHeartbeatMs(process.env.WHEREVER_HEARTBEAT_MS);
2143
+ // Consecutive pings sent with no inbound frame since. Reset to 0 on 'pong'
2144
+ // and on any 'message'.
2145
+ const missedPings = new WeakMap();
2002
2146
  const upgradeHandler = (req, socket, head) => {
2003
2147
  if (req.url?.startsWith('/ws')) {
2004
2148
  if (!authenticate(req, token)) {
@@ -2023,7 +2167,8 @@ async function main() {
2023
2167
  // Stable per-viewer identity (see WhereverClientConfig.clientKey). A client
2024
2168
  // that lost its socket silently (half-open TCP: phone sleep, network switch)
2025
2169
  // reconnects on a NEW socket while the old record still sits in the pool
2026
- // until the heartbeat reaper notices, up to 2x HEARTBEAT_MS later. That
2170
+ // until the heartbeat reaper notices, up to ~3x HEARTBEAT_MS later (it
2171
+ // tolerates one missed pong, see the heartbeat block above). That
2027
2172
  // phantom counted as "another viewer", which silently turned an explicit
2028
2173
  // "New Session Here" into a folder conflict (read-only attach to the folder's
2029
2174
  // existing session). Retiring the same key's previous connection HERE, before
@@ -2058,13 +2203,31 @@ async function main() {
2058
2203
  };
2059
2204
  clients.set(clientId, client);
2060
2205
  // Liveness: assume alive on connect; any pong (reply to the heartbeat ping
2061
- // frame below) re-marks the socket alive for the next interval.
2062
- liveSockets.add(ws);
2206
+ // frame below) OR any inbound message resets the missed-ping count.
2207
+ missedPings.set(ws, 0);
2063
2208
  ws.on('pong', () => {
2064
- liveSockets.add(ws);
2209
+ missedPings.set(ws, 0);
2210
+ });
2211
+ ws.on('message', () => {
2212
+ missedPings.set(ws, 0);
2065
2213
  });
2066
- sendWS(ws, { type: 'connected', clientId, serverVersion: getVersion() });
2067
- ws.on('message', async (data) => {
2214
+ sendWS(ws, { type: 'connected', clientId, serverVersion: getVersion(), capabilities: [UPLOAD_CAPABILITY], piVersion: piSdkInfo.version });
2215
+ ws.on('message', async (data, isBinary) => {
2216
+ // Binary frames are upload chunks (`upload.v1`), routed BEFORE any
2217
+ // JSON.parse: a chunk is raw bytes, never text. A binary frame that does not
2218
+ // start with the chunk kind byte is treated as JSON text as before, so a
2219
+ // client that happened to send JSON as binary keeps working.
2220
+ if (isBinary) {
2221
+ const buf = Buffer.isBuffer(data)
2222
+ ? data
2223
+ : Array.isArray(data)
2224
+ ? Buffer.concat(data)
2225
+ : Buffer.from(data);
2226
+ if (buf.length > 0 && buf[0] === CHUNK_FRAME_KIND) {
2227
+ handleUploadChunk(buf, client, sessionPool);
2228
+ return;
2229
+ }
2230
+ }
2068
2231
  let msg;
2069
2232
  try {
2070
2233
  msg = JSON.parse(data.toString());
@@ -2126,8 +2289,9 @@ async function main() {
2126
2289
  });
2127
2290
  const heartbeat = setInterval(() => {
2128
2291
  for (const ws of wss.clients) {
2129
- if (!liveSockets.has(ws)) {
2130
- // Missed the previous ping: treat as dead and reap. 'close' fires the
2292
+ const missed = missedPings.get(ws) ?? 0;
2293
+ if (missed >= HEARTBEAT_MAX_MISSES) {
2294
+ // Missed HEARTBEAT_MAX_MISSES consecutive pings: treat as dead and reap. 'close' fires the
2131
2295
  // existing teardown so the agent's session is released, not left dangling.
2132
2296
  // Log with whatever client/session context we can recover so a reaped
2133
2297
  // (hung) agent shows up as an event rather than as silence.
@@ -2148,7 +2312,7 @@ async function main() {
2148
2312
  catch { }
2149
2313
  continue;
2150
2314
  }
2151
- liveSockets.delete(ws);
2315
+ missedPings.set(ws, missed + 1);
2152
2316
  try {
2153
2317
  ws.ping();
2154
2318
  }
@@ -2257,6 +2421,26 @@ function clearConflictState(client) {
2257
2421
  client.conflictContinued = false;
2258
2422
  client.pendingCwd = undefined;
2259
2423
  }
2424
+ // Forget which session this client painted (see WSClient.paintedSessionFile).
2425
+ // NOT part of clearConflictState: a detach must not clear it.
2426
+ function clearPaintedSession(client) {
2427
+ client.paintedSessionFile = undefined;
2428
+ client.paintedSessionId = undefined;
2429
+ client.paintedCwd = undefined;
2430
+ }
2431
+ /**
2432
+ * TEST-ONLY lever: `WHEREVER_TEST_COLD_BUILD_DELAY_MS` holds a cold
2433
+ * `session_load`'s agent build open for that long before it starts, so tests can
2434
+ * act deterministically inside the paint-to-attach window (an upload during a
2435
+ * cold load, a leave/switch racing the late attach) instead of racing a fast
2436
+ * machine. Unset (every real deployment) it is a no-op.
2437
+ */
2438
+ function coldBuildTestDelay() {
2439
+ const ms = Number(process.env.WHEREVER_TEST_COLD_BUILD_DELAY_MS);
2440
+ if (!Number.isFinite(ms) || ms <= 0)
2441
+ return Promise.resolve();
2442
+ return new Promise((r) => setTimeout(r, ms));
2443
+ }
2260
2444
  // Is a DIFFERENT session in the same working folder currently being viewed? That
2261
2445
  // is the whole definition of a folder conflict: two agents pointed at one working
2262
2446
  // tree. Two viewers of the SAME conversation are not a conflict (they share one
@@ -2658,6 +2842,11 @@ async function handleWSMessage(msg, client, pool, clients, broadcast, onSessions
2658
2842
  // Same reasoning for the missing-folder lock: it belongs to the session we
2659
2843
  // are leaving, and must not leak into the one we are opening.
2660
2844
  client.folderMissingCwd = undefined;
2845
+ // And the painted session: a new load is about to paint another one.
2846
+ // Cleared BEFORE the first await because `joinSession` sends no leave: a
2847
+ // slow cold build of the previous session finishing during the read below
2848
+ // would otherwise still match it and attach the socket to the wrong session.
2849
+ clearPaintedSession(client);
2661
2850
  const meta = await pool.readSessionMeta(msg.sessionFile, INITIAL_HISTORY_LIMIT, msg.model);
2662
2851
  if ('error' in meta) {
2663
2852
  sendWS(client.ws, { type: 'session_error', error: meta.error });
@@ -2696,6 +2885,10 @@ async function handleWSMessage(msg, client, pool, clients, broadcast, onSessions
2696
2885
  client.readOnly = forcedReadOnly;
2697
2886
  client.conflictObserver = folderConflict;
2698
2887
  client.pendingCwd = meta.cwd;
2888
+ // Bind uploads (and this load's late attach) to the session painted now.
2889
+ client.paintedSessionFile = meta.sessionFile;
2890
+ client.paintedSessionId = meta.sessionId;
2891
+ client.paintedCwd = meta.cwd;
2699
2892
  // Paint immediately. `pending` is true when the live agent is not resident
2700
2893
  // yet, so the client keeps the composer disabled (with a "preparing
2701
2894
  // agent..." hint) until session_ready, while reading/scrolling work now.
@@ -2787,7 +2980,19 @@ async function handleWSMessage(msg, client, pool, clients, broadcast, onSessions
2787
2980
  // Cold: build the live agent in the background, then attach + signal ready.
2788
2981
  // Errors degrade to a session_error (the conversation stays readable).
2789
2982
  void (async () => {
2983
+ await coldBuildTestDelay();
2790
2984
  const result = await pool.loadSession(msg.sessionFile, msg.cwd, msg.model);
2985
+ // LATE ATTACH GUARD. The client may have left, switched or created
2986
+ // another session while the agent was building. Then the WHOLE tail
2987
+ // belongs to a session nobody is looking at: no stale session_error, no
2988
+ // attach (which would drag the socket back to this session), no read-only
2989
+ // re-derivation, session_ready, queue snapshot or conflict verdict. Just
2990
+ // let idle eviction reclaim the freshly built agent.
2991
+ if (client.paintedSessionFile !== meta.sessionFile) {
2992
+ if (!result.error)
2993
+ pool.scheduleIdleCheck(result.tracked.sessionFile);
2994
+ return;
2995
+ }
2791
2996
  if (result.error) {
2792
2997
  sendWS(client.ws, { type: 'session_error', sessionId: meta.sessionId, error: result.error });
2793
2998
  return;
@@ -2884,6 +3089,10 @@ async function handleWSMessage(msg, client, pool, clients, broadcast, onSessions
2884
3089
  // staring at a blocking overlay its 25s create watchdog would give up on
2885
3090
  // while git was still running. Creating a REMOTE (the other branch of that
2886
3091
  // dialog) is untouched and still happens inside createNewSession.
3092
+ //
3093
+ // A create is a new paint: forget the previous one first, so a cold load
3094
+ // still building cannot late-attach and uploads for it are refused.
3095
+ clearPaintedSession(client);
2887
3096
  if (msg.cloneRemote) {
2888
3097
  const targetPath = resolveCreateCwd(msg.cwd);
2889
3098
  // The restore broadcast is DERIVED from a path match against each
@@ -2926,6 +3135,9 @@ async function handleWSMessage(msg, client, pool, clients, broadcast, onSessions
2926
3135
  const folderOccupied = folderHasOtherViewedSession(pool, result.tracked.sessionFile, result.tracked.cwd);
2927
3136
  client.readOnly = folderOccupied || pool.isReadOnlyCwd(result.tracked.cwd);
2928
3137
  client.conflictObserver = folderOccupied;
3138
+ client.paintedSessionFile = result.tracked.sessionFile;
3139
+ client.paintedSessionId = result.tracked.sessionId;
3140
+ client.paintedCwd = result.tracked.cwd;
2929
3141
  sendWS(client.ws, {
2930
3142
  type: 'session_created',
2931
3143
  sessionId: result.tracked.sessionId,
@@ -2971,6 +3183,10 @@ async function handleWSMessage(msg, client, pool, clients, broadcast, onSessions
2971
3183
  // folder-missing load never attaches, so `sessionId` can already be null
2972
3184
  // here and the flag must be cleared regardless.)
2973
3185
  client.folderMissingCwd = undefined;
3186
+ // UNCONDITIONALLY, like the lock above: a leave during a cold load arrives
3187
+ // before the attach (sessionId still null or the previous session), and it
3188
+ // is what stops that load's late attach and refuses its uploads.
3189
+ clearPaintedSession(client);
2974
3190
  if (client.sessionId) {
2975
3191
  switchClientSession(client, null, pool, onSessionsUpdated);
2976
3192
  client.readOnly = false;
@@ -3353,20 +3569,24 @@ async function handleWSMessage(msg, client, pool, clients, broadcast, onSessions
3353
3569
  // dir. Refuse out loud rather than silently, for the same reason the
3354
3570
  // message handler does: a client only hides its composer when it AGREES it
3355
3571
  // is read-only, so any desync must be visible instead of swallowed.
3356
- if (client.readOnly) {
3357
- sendWS(client.ws, {
3358
- type: 'file_upload_error',
3359
- uploadId,
3360
- sessionId,
3361
- error: 'This session is read-only from here, so the file was not uploaded.',
3362
- });
3572
+ //
3573
+ // The verdict and the target folder both come from the session this socket
3574
+ // PAINTED (gateUploadWrite, docs/adr/0012): the verdict used to be the
3575
+ // attached session's while the file went to `msg.sessionId`'s folder, and
3576
+ // the folder came from the live session, absent during a cold build (tmp).
3577
+ const gate = gateUploadWrite(client, pool, sessionId);
3578
+ if (!gate.ok) {
3579
+ sendWS(client.ws, { type: 'file_upload_error', uploadId, sessionId, error: gate.reason });
3580
+ break;
3581
+ }
3582
+ const config = getWhereverConfig();
3583
+ const tooLarge = uploadTooLarge(Buffer.byteLength(String(data), 'base64'), uploadMaxBytes(config));
3584
+ if (tooLarge) {
3585
+ sendWS(client.ws, { type: 'file_upload_error', uploadId, sessionId, error: tooLarge });
3363
3586
  break;
3364
3587
  }
3365
3588
  try {
3366
- const tracked = pool.getSession(sessionId);
3367
- const cwd = tracked?.cwd;
3368
- const config = getWhereverConfig();
3369
- const targetDir = resolveUploadDir(config, cwd);
3589
+ const targetDir = resolveUploadDir(config, gate.cwd);
3370
3590
  fs.mkdirSync(targetDir, { recursive: true });
3371
3591
  const timestamp = Date.now();
3372
3592
  const safeFilename = `${timestamp}_${path.basename(filename)}`;
@@ -3391,8 +3611,130 @@ async function handleWSMessage(msg, client, pool, clients, broadcast, onSessions
3391
3611
  }
3392
3612
  break;
3393
3613
  }
3614
+ // Resumable chunked uploads (`upload.v1`, docs/adr/0012). index.ts only
3615
+ // routes: staging, sidecars, the per-id serial queue and GC live in
3616
+ // server/src/upload-staging.ts. Each call below reaches the staging queue
3617
+ // SYNCHRONOUSLY (no await before it), so frames for one id are queued in the
3618
+ // order they arrived on the socket.
3619
+ case 'upload_begin': {
3620
+ const { uploadId, sessionId, filename, size, mime } = msg;
3621
+ const replyId = typeof uploadId === 'string' ? uploadId.slice(0, 128) : '';
3622
+ const replySession = typeof sessionId === 'string' ? sessionId : '';
3623
+ const refuse = (error) => sendWS(client.ws, { type: 'file_upload_error', uploadId: replyId, sessionId: replySession, error });
3624
+ if (!isValidUploadId(uploadId)) {
3625
+ refuse('Invalid uploadId (expected 22 to 64 characters of A-Z, a-z, 0-9, _ or -).');
3626
+ break;
3627
+ }
3628
+ if (!replySession || typeof filename !== 'string' || !filename || !Number.isSafeInteger(size) || size < 0) {
3629
+ refuse('Missing or invalid parameters for upload_begin.');
3630
+ break;
3631
+ }
3632
+ const config = getWhereverConfig();
3633
+ const tooLarge = uploadTooLarge(size, uploadMaxBytes(config));
3634
+ if (tooLarge) {
3635
+ refuse(tooLarge);
3636
+ break;
3637
+ }
3638
+ let gateCwd;
3639
+ const authorize = (s) => {
3640
+ const gate = gateUploadWrite(client, pool, s.sessionId);
3641
+ if (!gate.ok)
3642
+ return gate.reason;
3643
+ gateCwd = gate.cwd;
3644
+ return null;
3645
+ };
3646
+ const result = await getUploadStaging().begin({
3647
+ uploadId,
3648
+ sessionId: replySession,
3649
+ filename,
3650
+ size,
3651
+ mime: typeof mime === 'string' ? mime : undefined,
3652
+ // Resolved ONCE, here, from the painted cwd the gate just approved.
3653
+ targetDir: () => resolveUploadDir(config, gateCwd),
3654
+ }, authorize).catch((err) => ({ ok: false, sessionId: replySession, error: err.message || 'Failed to start upload' }));
3655
+ if (!result.ok) {
3656
+ refuse(result.error);
3657
+ break;
3658
+ }
3659
+ sendWS(client.ws, {
3660
+ type: 'upload_offset',
3661
+ uploadId,
3662
+ offset: result.offset,
3663
+ ...(result.done ? { done: true, savedPath: result.savedPath } : {}),
3664
+ });
3665
+ break;
3666
+ }
3667
+ case 'upload_finish': {
3668
+ const { uploadId, sessionId } = msg;
3669
+ const replyId = typeof uploadId === 'string' ? uploadId.slice(0, 128) : '';
3670
+ const replySession = typeof sessionId === 'string' ? sessionId : '';
3671
+ if (!isValidUploadId(uploadId) || !replySession) {
3672
+ sendWS(client.ws, { type: 'file_upload_error', uploadId: replyId, sessionId: replySession, error: 'Invalid uploadId or sessionId for upload_finish.' });
3673
+ break;
3674
+ }
3675
+ const result = await getUploadStaging()
3676
+ .finish(uploadId, replySession, uploadAuthorizer(client, pool))
3677
+ .catch((err) => ({ ok: false, sessionId: replySession, error: err.message || 'Failed to save file' }));
3678
+ if (!result.ok) {
3679
+ sendWS(client.ws, { type: 'file_upload_error', uploadId, sessionId: replySession, error: result.error });
3680
+ break;
3681
+ }
3682
+ // The same frame the legacy path answers with, so completion looks alike.
3683
+ sendWS(client.ws, { type: 'file_uploaded', uploadId, sessionId: replySession, filename: result.filename, savedPath: result.savedPath });
3684
+ break;
3685
+ }
3686
+ case 'upload_abort': {
3687
+ // Not behind the write gate: it only deletes this upload's own staging
3688
+ // entry (never a saved file), and it must work from a socket that has
3689
+ // since become read-only. It is still bound to the recorded sessionId.
3690
+ const { uploadId, sessionId } = msg;
3691
+ const replySession = typeof sessionId === 'string' ? sessionId : '';
3692
+ if (!isValidUploadId(uploadId) || !replySession) {
3693
+ sendWS(client.ws, { type: 'file_upload_error', uploadId: typeof uploadId === 'string' ? uploadId.slice(0, 128) : '', sessionId: replySession, error: 'Invalid uploadId or sessionId for upload_abort.' });
3694
+ break;
3695
+ }
3696
+ const refused = await getUploadStaging().abort(uploadId, replySession).catch((err) => err.message || 'Failed to abort upload');
3697
+ if (refused)
3698
+ sendWS(client.ws, { type: 'file_upload_error', uploadId, sessionId: replySession, error: refused });
3699
+ break;
3700
+ }
3394
3701
  }
3395
3702
  }
3703
+ /** The write gate as a staging `Authorize`, judged against the sidecar's sessionId. */
3704
+ function uploadAuthorizer(client, pool) {
3705
+ return (s) => {
3706
+ const gate = gateUploadWrite(client, pool, s.sessionId);
3707
+ return gate.ok ? null : gate.reason;
3708
+ };
3709
+ }
3710
+ /**
3711
+ * A binary upload chunk (`upload.v1`). Parsed and handed to the staging queue in
3712
+ * the same tick it arrived, so per-socket order is preserved; the gate and the
3713
+ * offset check run inside the queue. Every chunk is acked with `upload_offset`
3714
+ * (the TRUE offset on a mismatch), every refusal is a `file_upload_error`.
3715
+ */
3716
+ function handleUploadChunk(buf, client, pool) {
3717
+ const frame = parseChunkFrame(buf);
3718
+ if (!frame.ok) {
3719
+ sendWS(client.ws, { type: 'file_upload_error', uploadId: frame.uploadId, sessionId: '', error: frame.error });
3720
+ return;
3721
+ }
3722
+ getUploadStaging()
3723
+ .writeChunk(frame.uploadId, frame.offset, frame.payload, uploadAuthorizer(client, pool))
3724
+ .catch((err) => ({ ok: false, sessionId: '', error: err.message || 'Failed to write upload chunk' }))
3725
+ .then((result) => {
3726
+ if (!result.ok) {
3727
+ sendWS(client.ws, { type: 'file_upload_error', uploadId: frame.uploadId, sessionId: result.sessionId, error: result.error });
3728
+ return;
3729
+ }
3730
+ sendWS(client.ws, {
3731
+ type: 'upload_offset',
3732
+ uploadId: frame.uploadId,
3733
+ offset: result.offset,
3734
+ ...(result.done ? { done: true, savedPath: result.savedPath } : {}),
3735
+ });
3736
+ });
3737
+ }
3396
3738
  /**
3397
3739
  * Extract image blocks from a tool result so the web frontend can render them
3398
3740
  * inline (mirroring the CLI's inline image display). The `read` tool returns