wherever-dev 0.24.0 → 0.25.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 (65) hide show
  1. package/CHANGELOG.md +17 -0
  2. package/dist/assistant-channels.d.ts +32 -1
  3. package/dist/assistant-channels.d.ts.map +1 -1
  4. package/dist/assistant-channels.js +57 -1
  5. package/dist/assistant-channels.js.map +1 -1
  6. package/dist/assistant-controller.d.ts +14 -0
  7. package/dist/assistant-controller.d.ts.map +1 -1
  8. package/dist/assistant-controller.js +21 -0
  9. package/dist/assistant-controller.js.map +1 -1
  10. package/dist/assistant-schedule.d.ts +42 -3
  11. package/dist/assistant-schedule.d.ts.map +1 -1
  12. package/dist/assistant-schedule.js +113 -2
  13. package/dist/assistant-schedule.js.map +1 -1
  14. package/dist/assistant-scheduler.d.ts +28 -6
  15. package/dist/assistant-scheduler.d.ts.map +1 -1
  16. package/dist/assistant-scheduler.js +59 -12
  17. package/dist/assistant-scheduler.js.map +1 -1
  18. package/dist/assistant-tools.d.ts +47 -13
  19. package/dist/assistant-tools.d.ts.map +1 -1
  20. package/dist/assistant-tools.js +37 -5
  21. package/dist/assistant-tools.js.map +1 -1
  22. package/dist/commands/config.d.ts +28 -0
  23. package/dist/commands/config.d.ts.map +1 -0
  24. package/dist/commands/config.js +128 -0
  25. package/dist/commands/config.js.map +1 -0
  26. package/dist/commands/install.d.ts.map +1 -1
  27. package/dist/commands/install.js +2 -0
  28. package/dist/commands/install.js.map +1 -1
  29. package/dist/config-dir.d.ts +13 -0
  30. package/dist/config-dir.d.ts.map +1 -1
  31. package/dist/config-dir.js +13 -0
  32. package/dist/config-dir.js.map +1 -1
  33. package/dist/index.js +167 -37
  34. package/dist/index.js.map +1 -1
  35. package/dist/protocol.d.ts +7 -0
  36. package/dist/protocol.d.ts.map +1 -1
  37. package/dist/session-pool.d.ts +23 -5
  38. package/dist/session-pool.d.ts.map +1 -1
  39. package/dist/session-pool.js +36 -35
  40. package/dist/session-pool.js.map +1 -1
  41. package/package.json +1 -1
  42. package/public/_app/immutable/chunks/{jBzVXpuo.js → CRvF0-wF.js} +2 -2
  43. package/public/_app/immutable/chunks/{jBzVXpuo.js.map → CRvF0-wF.js.map} +1 -1
  44. package/public/_app/immutable/chunks/{Ba0iJyN2.js → ClUQt0nO.js} +2 -2
  45. package/public/_app/immutable/chunks/{Ba0iJyN2.js.map → ClUQt0nO.js.map} +1 -1
  46. package/public/_app/immutable/chunks/XW0SPyOK.js +2 -0
  47. package/public/_app/immutable/chunks/{BfCwf84t.js.map → XW0SPyOK.js.map} +1 -1
  48. package/public/_app/immutable/entry/{app.CePvTLA2.js → app.D1EX_9pb.js} +3 -3
  49. package/public/_app/immutable/entry/{app.CePvTLA2.js.map → app.D1EX_9pb.js.map} +1 -1
  50. package/public/_app/immutable/entry/start.ga0QZFSJ.js +2 -0
  51. package/public/_app/immutable/entry/start.ga0QZFSJ.js.map +1 -0
  52. package/public/_app/immutable/nodes/{0.ydSaxbgZ.js → 0.DsJW22vw.js} +2 -2
  53. package/public/_app/immutable/nodes/{0.ydSaxbgZ.js.map → 0.DsJW22vw.js.map} +1 -1
  54. package/public/_app/immutable/nodes/{1.T9BouUHS.js → 1.BsL25UTD.js} +2 -2
  55. package/public/_app/immutable/nodes/{1.T9BouUHS.js.map → 1.BsL25UTD.js.map} +1 -1
  56. package/public/_app/immutable/nodes/2.DO5lRCyx.js +124 -0
  57. package/public/_app/immutable/nodes/2.DO5lRCyx.js.map +1 -0
  58. package/public/_app/version.json +1 -1
  59. package/public/index.html +10 -10
  60. package/public/service-worker.js +1 -1
  61. package/public/_app/immutable/chunks/BfCwf84t.js +0 -2
  62. package/public/_app/immutable/entry/start.MB6ZjVGe.js +0 -2
  63. package/public/_app/immutable/entry/start.MB6ZjVGe.js.map +0 -1
  64. package/public/_app/immutable/nodes/2.D_6BVhWL.js +0 -123
  65. package/public/_app/immutable/nodes/2.D_6BVhWL.js.map +0 -1
package/dist/index.js CHANGED
@@ -8,8 +8,8 @@ import { readDrafts, addDraft, deleteDraft, validateDraftInput } from './drafts.
8
8
  import { canonicalPath, startAssistantFolder } from './assistant-folder.js';
9
9
  import { AssistantController } from './assistant-controller.js';
10
10
  import { AssistantScheduler } from './assistant-scheduler.js';
11
- import { assistantNotActiveError, setTimezone, testNotification, WEB_TIMEZONE_SOURCE, } from './assistant-tools.js';
12
- import { ChannelDispatcher } from './assistant-channels.js';
11
+ import { assistantNotActiveError, testNotification, webTimezoneReport, } from './assistant-tools.js';
12
+ import { ChannelDispatcher, reportDroppedBeyondChannels } from './assistant-channels.js';
13
13
  import { WebPushChannel, resolveVapidSubject, validateSubscription } from './web-push.js';
14
14
  import { TelegramChannel } from './telegram-channel.js';
15
15
  import { normalizeToolCalls } from './telegram-replies.js';
@@ -38,11 +38,17 @@ import { fileURLToPath } from 'node:url';
38
38
  import os from 'node:os';
39
39
  import { execFileSync } from 'node:child_process';
40
40
  import { runInstall, runUninstall, runServiceStatus, parseInstallOptions, printInstallHelp, } from './commands/install.js';
41
+ import { runConfigCommand } from './commands/config.js';
42
+ import { getWhereverConfigPath } from './config-dir.js';
41
43
  const __filename = fileURLToPath(import.meta.url);
42
44
  const __dirname = path.dirname(__filename);
43
45
  const devStaticPath = path.resolve(__dirname, '../../web/build');
44
46
  const prodStaticPath = path.resolve(__dirname, '../public');
45
- const staticDir = fs.existsSync(devStaticPath) ? devStaticPath : prodStaticPath;
47
+ // TEST-ONLY lever: `WHEREVER_TEST_STATIC_DIR` serves the web app from that
48
+ // directory, so a test of static serving does not depend on a web build being
49
+ // present (CI's server jobs build none). Unset (every real deployment) it is a
50
+ // no-op.
51
+ const staticDir = process.env.WHEREVER_TEST_STATIC_DIR || (fs.existsSync(devStaticPath) ? devStaticPath : prodStaticPath);
46
52
  // When true (set via --debug), the served dashboard index.html is rewritten so
47
53
  // eruda's custom-plugin loader is enabled. Plugin loading is the only eruda
48
54
  // feature that takes a URL parameter into a <script src>, so it is kept off by
@@ -996,6 +1002,11 @@ async function main() {
996
1002
  debugEnabled = debug;
997
1003
  console.log(`[wherever] pi SDK ${piSdkInfo.version}: ` +
998
1004
  (piSdkInfo.tier === 'bundled' ? `bundled (${piSdkInfo.why})` : `${piSdkInfo.tier}, from ${piSdkInfo.root} (${piSdkInfo.why})`));
1005
+ // Where the config comes from (ADR 0022): reading it never creates it, so a
1006
+ // missing file is said here instead of being silently seeded.
1007
+ const configPath = getWhereverConfigPath();
1008
+ console.log(`[wherever] config: ${configPath} ` +
1009
+ (fs.existsSync(configPath) ? '(found)' : '(not found, using built-in defaults)'));
999
1010
  const sessionPool = new SessionPool(idleTimeout, { getStarred: readStarredSet });
1000
1011
  await sessionPool.initialize();
1001
1012
  // The assistant folder (opt-in via `assistantFolder`, see assistant-folder.ts):
@@ -1005,10 +1016,15 @@ async function main() {
1005
1016
  const assistant = startAssistantFolder(getWhereverConfig());
1006
1017
  sessionPool.setAssistantFolder(assistant.status.active ? (assistant.status.folder ?? undefined) : undefined);
1007
1018
  // The assistant tools (assistant-tools.ts) in every server session, and the
1008
- // timezone line in the assistant folder: registered while `assistantFolder`
1009
- // is CONFIGURED. The backend is the scheduler, set below once it has started;
1010
- // until then, and for a server refused by the folder lock, every tool answers
1011
- // the lock-state error. Unset = no hooks, so sessions are exactly as before.
1019
+ // timezone line in the assistant folder: registered ONLY while the assistant
1020
+ // is ACTIVE (configured AND this server holds the folder lock). The backend is
1021
+ // the scheduler, set below once it has started; in that short boot window the
1022
+ // tools answer "the assistant scheduler is still starting". A server refused by the lock (or a lock error)
1023
+ // sets NO session hooks, so its sessions are exactly as with the assistant
1024
+ // unset (decision of assistant-schedule-tools-absent-when-not-active,
1025
+ // reversing assistant-schedule-tools-server decision 4). The CLI twin ops
1026
+ // still get the hooks while CONFIGURED, so a terminal pi's twin (which cannot
1027
+ // be hidden server-side) answers the lock-state error.
1012
1028
  let assistantBackend = null;
1013
1029
  // `assistant_notify`'s backend (the channel dispatcher + the scheduler's job
1014
1030
  // mapping), set below once the channels have started. The tool itself is
@@ -1022,7 +1038,9 @@ async function main() {
1022
1038
  folder: assistant.status.folder,
1023
1039
  access: () => assistantBackend
1024
1040
  ? { ok: true, backend: assistantBackend }
1025
- : { ok: false, error: assistantNotActiveError(assistant.status.lock) },
1041
+ : assistant.status.active
1042
+ ? { ok: false, error: 'the assistant scheduler is still starting; try again in a moment' }
1043
+ : { ok: false, error: assistantNotActiveError(assistant.status.lock) },
1026
1044
  ...(assistant.status.active
1027
1045
  ? {
1028
1046
  notify: () => notifyBackend
@@ -1031,7 +1049,8 @@ async function main() {
1031
1049
  }
1032
1050
  : {}),
1033
1051
  };
1034
- sessionPool.setAssistantSessionHooks(assistantHooks);
1052
+ if (assistant.status.active)
1053
+ sessionPool.setAssistantSessionHooks(assistantHooks);
1035
1054
  }
1036
1055
  const currentTimezone = () => {
1037
1056
  try {
@@ -1074,16 +1093,68 @@ async function main() {
1074
1093
  if (!c.isCliBridge)
1075
1094
  sendWS(c.ws, update);
1076
1095
  }
1096
+ refreshRetiredViewers();
1077
1097
  },
1078
1098
  // Messages a reset or an aborted settle dropped: reported to the
1079
1099
  // channels they came from (the dispatcher exists by then; before it
1080
- // does, nothing has been sent from a channel, so nothing is lost).
1081
- onDropped: (dropped) => channelDispatcher?.reportDropped(dropped),
1100
+ // does, nothing has been sent from a channel, so nothing is lost);
1101
+ // the web's own become a notice to the session's web viewers (the
1102
+ // retired session's, on a reset), and a scheduled job's are logged.
1103
+ onDropped: (dropped) => {
1104
+ channelDispatcher?.reportDropped(dropped);
1105
+ reportDroppedBeyondChannels(dropped, {
1106
+ notifyWebViewers: (sessionFile, message) => {
1107
+ const sessionId = sessionPool.getSession(sessionFile)?.sessionId;
1108
+ if (!sessionId)
1109
+ return;
1110
+ const notice = { type: 'session_notice', sessionId, level: 'warning', message };
1111
+ for (const c of clients.values()) {
1112
+ if (!c.isCliBridge && c.sessionId === sessionFile)
1113
+ sendWS(c.ws, notice);
1114
+ }
1115
+ },
1116
+ });
1117
+ },
1082
1118
  })
1083
1119
  : null;
1084
1120
  if (assistantController) {
1085
1121
  sessionPool.onSessionCreated = (sessionFile, cwd) => assistantController.handleSessionCreated(sessionFile, cwd);
1086
1122
  }
1123
+ /**
1124
+ * The pointer moved: re-evaluate every web viewer's RETIRED verdict (ADR 0020)
1125
+ * and tell those whose verdict changed, live (`assistant_retired`), so a tab
1126
+ * still on the old session turns read-only without a reload. Keyed on the
1127
+ * PAINTED session, so a cold load still building is covered too (its attach
1128
+ * re-derives read-only from the flag). Then every folder-conflict verdict is
1129
+ * re-sent: the newly retired session stopped being an occupant.
1130
+ */
1131
+ function refreshRetiredViewers() {
1132
+ if (!assistantController)
1133
+ return;
1134
+ for (const c of clients.values()) {
1135
+ if (c.isCliBridge || !c.paintedSessionFile || !c.paintedCwd || !c.paintedSessionId)
1136
+ continue;
1137
+ const retired = assistantController.isRetired(c.paintedSessionFile, c.paintedCwd);
1138
+ if (retired === (c.assistantRetired === true))
1139
+ continue;
1140
+ c.assistantRetired = retired || undefined;
1141
+ if (retired) {
1142
+ // Hard: it replaces any folder-conflict observation the client was in.
1143
+ c.readOnly = true;
1144
+ c.conflictObserver = false;
1145
+ }
1146
+ else {
1147
+ // Became current again (the pointer moved onto the painted session):
1148
+ // only the remaining reasons decide.
1149
+ c.readOnly =
1150
+ sessionPool.isReadOnlyCwd(c.paintedCwd) ||
1151
+ c.folderMissingCwd !== undefined ||
1152
+ (c.conflictObserver === true && !c.conflictContinued);
1153
+ }
1154
+ sendWS(c.ws, { type: 'assistant_retired', sessionId: c.paintedSessionId, retired, readOnly: c.readOnly });
1155
+ }
1156
+ broadcastFolderConflicts();
1157
+ }
1087
1158
  // The assistant scheduler (assistant-scheduler.ts, ADR 0015): fires the jobs in
1088
1159
  // `<assistantFolder>/schedule.json`. Built and started ONLY while the
1089
1160
  // assistant is active (configured AND this server holds the folder lock), so
@@ -1214,14 +1285,17 @@ async function main() {
1214
1285
  }
1215
1286
  };
1216
1287
  /**
1217
- * A web client's timezone report (`client_timezone`, sent on connect): made the
1218
- * user's current timezone when it differs, only while the assistant is active.
1219
- * Otherwise ignored, so nothing is written. An unknown zone is logged and ignored.
1288
+ * A web client's timezone report (`client_timezone`, sent only when the
1289
+ * device's zone moved, ADR 0019): applied by `webTimezoneReport` (a first
1290
+ * report never overrides `assistant_set_timezone`), only while the assistant
1291
+ * is active. Otherwise ignored, so nothing is written. An unknown zone is
1292
+ * logged and ignored.
1220
1293
  */
1221
- const onClientTimezone = (timezone) => {
1294
+ const onClientTimezone = (report) => {
1295
+ const { timezone } = report;
1222
1296
  if (!assistantBackend || typeof timezone !== 'string' || !timezone.trim())
1223
1297
  return;
1224
- const r = setTimezone(assistantBackend, { timezone }, WEB_TIMEZONE_SOURCE);
1298
+ const r = webTimezoneReport(assistantBackend, report);
1225
1299
  if (!r.ok)
1226
1300
  console.warn(`[wherever] assistant: ignoring the web's timezone report: ${r.error}`);
1227
1301
  };
@@ -1387,7 +1461,7 @@ async function main() {
1387
1461
  // readOnly rides along every time so the client's composer mirrors the
1388
1462
  // server's authority rather than inferring it from `active`.
1389
1463
  for (const c of clients.values()) {
1390
- sendFolderConflict(c, sessionPool);
1464
+ sendFolderConflict(c, sessionPool, assistantController);
1391
1465
  }
1392
1466
  }
1393
1467
  function broadcastAgentEvent(sessionFile, event) {
@@ -3002,6 +3076,8 @@ function clearPaintedSession(client) {
3002
3076
  client.paintedSessionFile = undefined;
3003
3077
  client.paintedSessionId = undefined;
3004
3078
  client.paintedCwd = undefined;
3079
+ // The retired verdict describes the painted session, so it goes with it.
3080
+ client.assistantRetired = undefined;
3005
3081
  }
3006
3082
  /**
3007
3083
  * TEST-ONLY lever: `WHEREVER_TEST_COLD_BUILD_DELAY_MS` holds a cold
@@ -3020,10 +3096,21 @@ function coldBuildTestDelay() {
3020
3096
  // is the whole definition of a folder conflict: two agents pointed at one working
3021
3097
  // tree. Two viewers of the SAME conversation are not a conflict (they share one
3022
3098
  // agent), and a session nobody is attached to is not one either (idle, no turns).
3023
- function folderHasOtherViewedSession(pool, mySessionFile, cwd) {
3099
+ //
3100
+ // A RETIRED assistant session (ADR 0020) never counts as an occupant: the
3101
+ // conflict would be one our own reset created, and it would open the CURRENT
3102
+ // session read-only behind the banner while a tab still views the old one.
3103
+ function folderHasOtherViewedSession(pool, mySessionFile, cwd, assistant) {
3024
3104
  return pool
3025
3105
  .getAllSessions()
3026
- .some((s) => s.sessionFile !== mySessionFile && s.cwd === cwd && s.clients.size > 0);
3106
+ .some((s) => s.sessionFile !== mySessionFile &&
3107
+ s.cwd === cwd &&
3108
+ s.clients.size > 0 &&
3109
+ !isRetiredAssistantSession(assistant, s.sessionFile, s.cwd));
3110
+ }
3111
+ /** Is this a retired assistant session (ADR 0020)? Always false while the assistant is not active. */
3112
+ function isRetiredAssistantSession(assistant, sessionFile, cwd) {
3113
+ return assistant !== null && assistant.isRetired(sessionFile, cwd);
3027
3114
  }
3028
3115
  // Recompute ONE client's folder-conflict state and settle the read-only it
3029
3116
  // imposed: releasing it once the conflict no longer holds is part of resolving,
@@ -3031,13 +3118,15 @@ function folderHasOtherViewedSession(pool, mySessionFile, cwd) {
3031
3118
  // cold attach and the "Continue anyway" reply so all three speak with one
3032
3119
  // authority. Returns null for connections the banner does not apply to (CLI
3033
3120
  // bridges, clients not attached to a session).
3034
- function resolveFolderConflictState(c, pool) {
3121
+ function resolveFolderConflictState(c, pool, assistant) {
3035
3122
  if (c.isCliBridge || !c.sessionId)
3036
3123
  return null;
3037
3124
  const mine = pool.getSession(c.sessionId);
3038
3125
  if (!mine)
3039
3126
  return null;
3040
- const active = folderHasOtherViewedSession(pool, mine.sessionFile, mine.cwd);
3127
+ // A retired assistant session is not a party to a folder conflict at all: its
3128
+ // own (hard) verdict already says why it is read-only and what to open instead.
3129
+ const active = c.assistantRetired !== true && folderHasOtherViewedSession(pool, mine.sessionFile, mine.cwd, assistant);
3041
3130
  // NOTE: every conflict is now between DIFFERENT session files in one folder --
3042
3131
  // an observer gets its own new session (session_new) or loads its own
3043
3132
  // (session_load), never the occupant's file -- so the scan above sees them all.
@@ -3055,17 +3144,20 @@ function resolveFolderConflictState(c, pool) {
3055
3144
  }
3056
3145
  return { cwd: mine.cwd, active };
3057
3146
  }
3058
- // Read-only PRECEDENCE in one place. Of the three reasons a client can be
3059
- // read-only, two are HARD and one is dismissible:
3147
+ // Read-only PRECEDENCE in one place. Of the four reasons a client can be
3148
+ // read-only, three are HARD and one is dismissible:
3060
3149
  // - a configured `sessions.readOnly` folder: a policy rule, never lifted;
3061
3150
  // - FOLDER MISSING: the working folder does not exist on this machine, so
3062
3151
  // there is nothing to drive; lifted only by restoring it and RELOADING;
3152
+ // - a RETIRED assistant session (ADR 0020): not the current pointer session
3153
+ // in `assistantFolder`; writing would fork the assistant's conversation into
3154
+ // a session nobody points at, so the remedy is opening the current one;
3063
3155
  // - a folder conflict: two live sessions in one folder, lifted by the user's
3064
3156
  // "Continue anyway".
3065
3157
  // Every site that LIFTS read-only asks this first, so the dismissible reason can
3066
3158
  // never dismiss a hard one.
3067
3159
  function hasHardReadOnly(client, pool, cwd) {
3068
- return pool.isReadOnlyCwd(cwd) || client.folderMissingCwd !== undefined;
3160
+ return pool.isReadOnlyCwd(cwd) || client.folderMissingCwd !== undefined || client.assistantRetired === true;
3069
3161
  }
3070
3162
  // ---------------------------------------------------------------------------
3071
3163
  // Restore jobs over the WebSocket
@@ -3276,8 +3368,8 @@ async function cloneForNewSession(targetPath, clients, pool, onStarted) {
3276
3368
  // Resolve and report in one step. Every folder_conflict frame goes out through
3277
3369
  // here, so the `readOnly` it carries can never drift from the authority that
3278
3370
  // produced `active`.
3279
- function sendFolderConflict(client, pool) {
3280
- const verdict = resolveFolderConflictState(client, pool);
3371
+ function sendFolderConflict(client, pool, assistant) {
3372
+ const verdict = resolveFolderConflictState(client, pool, assistant);
3281
3373
  if (!verdict)
3282
3374
  return;
3283
3375
  sendWS(client.ws, {
@@ -3318,8 +3410,8 @@ function sendQueueSnapshot(client, sessionFile, sessionId, pool) {
3318
3410
  async function handleWSMessage(msg, client, pool, clients, broadcast, onSessionsUpdated, assistantController = null, cliRequests = null, onClientTimezone = () => { }) {
3319
3411
  switch (msg.type) {
3320
3412
  case 'client_timezone':
3321
- // The web's timezone report on connect (see onClientTimezone in main).
3322
- onClientTimezone(msg.timezone);
3413
+ // The web's timezone report when its device moved (see onClientTimezone in main).
3414
+ onClientTimezone({ timezone: msg.timezone, first: msg.first });
3323
3415
  break;
3324
3416
  case 'assistant_open':
3325
3417
  case 'assistant_reset': {
@@ -3483,8 +3575,13 @@ async function handleWSMessage(msg, client, pool, clients, broadcast, onSessions
3483
3575
  // client starts read-only (observing) until the user clicks "Continue
3484
3576
  // anyway" (folder_conflict_continue), which lifts read-only WITHOUT
3485
3577
  // aborting the other session -- both then run concurrently.
3486
- const conflict = pool.detectConflict(meta.sessionFile, meta.cwd);
3487
- const folderConflict = conflict.conflict && !!conflict.otherSessionId;
3578
+ //
3579
+ // A RETIRED assistant session (ADR 0020) is neither a party to a conflict
3580
+ // nor an occupant of one: it is hard read-only on its own account, and a
3581
+ // tab still viewing it must not lock the CURRENT session out.
3582
+ const retired = isRetiredAssistantSession(assistantController, meta.sessionFile, meta.cwd);
3583
+ const conflict = pool.detectConflict(meta.sessionFile, meta.cwd, (s) => isRetiredAssistantSession(assistantController, s.sessionFile, s.cwd));
3584
+ const folderConflict = !retired && conflict.conflict && !!conflict.otherSessionId;
3488
3585
  // This session's working folder is not usable as a working folder. TWO
3489
3586
  // things produce that, and they are one state because they have one
3490
3587
  // remedy and one rendering:
@@ -3504,11 +3601,13 @@ async function handleWSMessage(msg, client, pool, clients, broadcast, onSessions
3504
3601
  const folderMissing = meta.folderMissing || restoreInFlight;
3505
3602
  client.folderMissingCwd = folderMissing ? meta.cwd : undefined;
3506
3603
  // A session whose cwd matches a sessions.readOnly glob is forced read-only.
3507
- // A missing folder forces it too (hard, see hasHardReadOnly). A folder
3508
- // conflict also starts the client read-only until they continue.
3509
- const forcedReadOnly = meta.readOnly || folderMissing || folderConflict;
3604
+ // A missing folder forces it too (hard, see hasHardReadOnly), and so does a
3605
+ // retired assistant session. A folder conflict also starts the client
3606
+ // read-only until they continue.
3607
+ const forcedReadOnly = meta.readOnly || folderMissing || retired || folderConflict;
3510
3608
  client.readOnly = forcedReadOnly;
3511
3609
  client.conflictObserver = folderConflict;
3610
+ client.assistantRetired = retired || undefined;
3512
3611
  client.pendingCwd = meta.cwd;
3513
3612
  // Bind uploads (and this load's late attach) to the session painted now.
3514
3613
  client.paintedSessionFile = meta.sessionFile;
@@ -3527,6 +3626,7 @@ async function handleWSMessage(msg, client, pool, clients, broadcast, onSessions
3527
3626
  readOnly: forcedReadOnly,
3528
3627
  folderConflict,
3529
3628
  folderMissing,
3629
+ ...(retired ? { assistantRetired: true } : {}),
3530
3630
  contextUsage: meta.resident ? (pool.getContextUsage(meta.sessionFile) ?? null) : null,
3531
3631
  // A resident session mid-/reload has no usable agent yet: paint it as
3532
3632
  // pending; the reload's own session_ready (sent to every viewer, this
@@ -3637,9 +3737,12 @@ async function handleWSMessage(msg, client, pool, clients, broadcast, onSessions
3637
3737
  // it, while `message` dropped their sends in silence. The conflict having
3638
3738
  // RESOLVED during the build is handled just below by the verdict, which
3639
3739
  // re-scans and releases read-only.
3740
+ // The retired verdict is read from the client, not from `retired`: the
3741
+ // pointer may have moved during the build (refreshRetiredViewers).
3640
3742
  client.readOnly =
3641
3743
  meta.readOnly ||
3642
3744
  pool.isReadOnlyCwd(result.tracked.cwd) ||
3745
+ client.assistantRetired === true ||
3643
3746
  (client.conflictObserver === true && !client.conflictContinued);
3644
3747
  sendWS(client.ws, {
3645
3748
  type: 'session_ready',
@@ -3657,7 +3760,7 @@ async function handleWSMessage(msg, client, pool, clients, broadcast, onSessions
3657
3760
  // user continued through it). session_ready carries no readOnly, and the
3658
3761
  // periodic conflict broadcast is throttled, so state the verdict here
3659
3762
  // explicitly rather than leaving the composer to guess for up to 2s.
3660
- sendFolderConflict(client, pool);
3763
+ sendFolderConflict(client, pool, assistantController);
3661
3764
  })();
3662
3765
  break;
3663
3766
  }
@@ -3757,9 +3860,20 @@ async function handleWSMessage(msg, client, pool, clients, broadcast, onSessions
3757
3860
  // clicks "Continue anyway", which lifts read-only WITHOUT touching the other
3758
3861
  // session. The difference from before is that the banner now sits on the
3759
3862
  // conversation they asked for, so continuing does what it says.
3760
- const folderOccupied = folderHasOtherViewedSession(pool, result.tracked.sessionFile, result.tracked.cwd);
3761
- client.readOnly = folderOccupied || pool.isReadOnlyCwd(result.tracked.cwd);
3863
+ //
3864
+ // A session created IN the assistant folder becomes the current assistant
3865
+ // session through the pool's session-created callback, which the
3866
+ // controller runs on its serial queue: wait for it, so the verdict below
3867
+ // sees the pointer already on the new session (and the one it replaced
3868
+ // already retired, so it is no occupant). Only for that folder: the queue
3869
+ // can hold a seconds-long load, which no other create should wait on.
3870
+ if (assistantController?.isFolder(result.tracked.cwd))
3871
+ await assistantController.idle();
3872
+ const retired = isRetiredAssistantSession(assistantController, result.tracked.sessionFile, result.tracked.cwd);
3873
+ const folderOccupied = !retired && folderHasOtherViewedSession(pool, result.tracked.sessionFile, result.tracked.cwd, assistantController);
3874
+ client.readOnly = retired || folderOccupied || pool.isReadOnlyCwd(result.tracked.cwd);
3762
3875
  client.conflictObserver = folderOccupied;
3876
+ client.assistantRetired = retired || undefined;
3763
3877
  client.paintedSessionFile = result.tracked.sessionFile;
3764
3878
  client.paintedSessionId = result.tracked.sessionId;
3765
3879
  client.paintedCwd = result.tracked.cwd;
@@ -3772,6 +3886,7 @@ async function handleWSMessage(msg, client, pool, clients, broadcast, onSessions
3772
3886
  isStreaming: pool.isStreaming(result.tracked.sessionFile),
3773
3887
  readOnly: client.readOnly,
3774
3888
  folderConflict: folderOccupied,
3889
+ ...(retired ? { assistantRetired: true } : {}),
3775
3890
  });
3776
3891
  sendWS(client.ws, {
3777
3892
  type: 'message_history',
@@ -3861,7 +3976,7 @@ async function handleWSMessage(msg, client, pool, clients, broadcast, onSessions
3861
3976
  // was already in flight when the continue was sent, so an in-flight update
3862
3977
  // carrying the pre-continue readOnly:true cannot leave the composer
3863
3978
  // disabled with the banner's button already gone.
3864
- sendFolderConflict(client, pool);
3979
+ sendFolderConflict(client, pool, assistantController);
3865
3980
  break;
3866
3981
  }
3867
3982
  case 'restore_start': {
@@ -3967,6 +4082,17 @@ async function handleWSMessage(msg, client, pool, clients, broadcast, onSessions
3967
4082
  }
3968
4083
  if (!client.sessionId)
3969
4084
  return;
4085
+ if (client.assistantRetired) {
4086
+ // A retired assistant session (ADR 0020): hard, so do not point at the
4087
+ // banner's "Continue anyway", point at the current session instead.
4088
+ sendWS(client.ws, {
4089
+ type: 'session_error',
4090
+ sessionId: msg.sessionId,
4091
+ error: 'This assistant session was retired (the assistant was reset), so it is read-only and the message was not delivered. ' +
4092
+ 'Open the current assistant session to continue.',
4093
+ });
4094
+ return;
4095
+ }
3970
4096
  if (client.readOnly) {
3971
4097
  // Never swallow a send. This is a legitimate refusal for an observe-only
3972
4098
  // session (a sessions.readOnly folder, or a folder conflict not continued
@@ -4435,6 +4561,7 @@ function getVersion() {
4435
4561
  * Subcommand dispatch. Every action is an explicit verb:
4436
4562
  * - `wherever start [server flags]` runs the server
4437
4563
  * - `wherever install|uninstall|service-status` manage the background service
4564
+ * - `wherever config init|show` write a starter config / show the effective one
4438
4565
  * - `wherever --version` (or `-v` / `version`) prints the version
4439
4566
  * - bare `wherever` (or `help`) prints usage
4440
4567
  * Server flags after `start` are consumed by parseArgs() (which reads
@@ -4464,6 +4591,9 @@ function dispatch() {
4464
4591
  case 'status':
4465
4592
  runServiceStatus(parseInstallOptions(rest));
4466
4593
  return;
4594
+ case 'config':
4595
+ process.exitCode = runConfigCommand(rest);
4596
+ return;
4467
4597
  case 'version':
4468
4598
  case '--version':
4469
4599
  case '-v':