wherever-dev 0.18.3 → 0.18.5

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