@skitterbyte/skitterspec-linear 19.12.0 → 19.14.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.
@@ -523,6 +523,12 @@ through to a documented conservative default; see the field notes below.
523
523
  // "local" — you are at the machine holding the page; it binds 127.0.0.1.
524
524
  // "remote" — you are not; it binds every interface so the page opens.
525
525
  // "detect" — work it out (the default); cannot-tell binds 127.0.0.1.
526
+ // SKITTERSPEC_READER=local|remote in the environment outranks this key: a
527
+ // wrapper that runs the engine on another machine (a VM's `prlctl exec`)
528
+ // speaks for that machine alone. A reader on another machine — this key or
529
+ // that variable set to "remote", ssh, or a Windows session with no desktop
530
+ // (no SESSIONNAME: `prlctl exec`, sshd, a scheduled task) — gets no `local` tier while
531
+ // `network` has a URL, since 127.0.0.1 is the engine's machine.
526
532
  // An explicit "local"/"remote" is BELIEVED WITHOUT SNIFFING: you know where
527
533
  // you are reading, and no signal outranks being told. Detection is only the
528
534
  // default, and it has three outcomes rather than two — local, remote, and
@@ -164,6 +164,30 @@ on. Dropping the line is what left a reader who had walked out of the house with
164
164
  nothing on screen to tell them a remote page was even possible — they could not
165
165
  ask for what they could not see.
166
166
 
167
+ **One exception: a reader on another machine sees no `local` line.** This is
168
+ the third amendment, and it argues from the rule's own reason. The rule keeps a
169
+ line so the reader can see a door they could ask to have opened. But when the
170
+ engine runs on one machine and the reader is on another — a wrapper running it
171
+ inside a VM, or an ssh session — `127.0.0.1` is the engine's machine, not the
172
+ reader's. That door never opens, whatever anyone asks. It was also first in the
173
+ stack, the link habit reaches for, and it cost a timeout on every review. So the
174
+ engine hides it, on `SKITTERSPEC_READER=remote` (`local` outranks everything
175
+ below it), the committed `review.reader`, ssh, or a Windows session with no
176
+ desktop (no `SESSIONNAME`, which is what `prlctl exec`, the OpenSSH server and a
177
+ scheduled task all look like). It hides it only
178
+ when `network` has a URL to take its place; otherwise the line stays and says
179
+ it is unreachable.
180
+
181
+ **That last signal is detection, allowed here for what a wrong guess costs.** The network URL is the same server, so it opens from
182
+ the engine's own machine too. A reader wrongly judged to be elsewhere gets the
183
+ second-best link, never a page that will not open. Detection has done harm
184
+ before when it decided whether to *serve*, because a wrong guess there removed
185
+ the verdict loop. Nothing like that is at stake here. The skill still decides
186
+ nothing. A tier marked `hidden` in `--json` is absent from the printed stack, so
187
+ copying the stack still produces the right banner. The holding line names the
188
+ engine's `covers` — *the wait covers network* — never a door the stack did not
189
+ show.
190
+
167
191
  **The `network` tier may carry alternates, and they are part of it — not a fourth tier.**
168
192
  The engine offers the other addresses this machine has (a
169
193
  tailnet one, for a reader off the wifi) as `also:` lines under `network`, each
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@skitterbyte/skitterspec-linear",
3
- "version": "19.12.0",
3
+ "version": "19.14.0",
4
4
  "description": "Spec-driven development for Claude Code, with one-way Linear sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus /spec-status · /spec-push and the spec-sync CLI. The repo is canonical; Linear is a generated mirror. Install this OR the base, not both.",
5
5
  "keywords": [
6
6
  "claude",
package/src/cli.js CHANGED
@@ -114,6 +114,8 @@ const {
114
114
  collectReview,
115
115
  reviewTierStack,
116
116
  reviewTierLine,
117
+ reviewStackText,
118
+ waitCovers,
117
119
  isTailnetAddress,
118
120
  tailnetLabel,
119
121
  renderReviewPage,
@@ -1027,8 +1029,9 @@ async function serveTadaPage({ window, flags, recap }) {
1027
1029
  const q = tadaQuery({ ...flags, on: flags.on || (flags.since ? null : localDay(window.since)) })
1028
1030
  const withQ = (u) => (u ? `${u}${q}` : u)
1029
1031
  const page = { ...served, loopbackUrl: withQ(served.loopbackUrl), url: withQ(served.url), alternates: (served.alternates || []).map(withQ) }
1030
- const tiers = reviewTierStack({ served: page, fileUrl: null, publishedUrl: null, config })
1031
- process.stdout.write(`page: ${humanLabel(window)}\n${tiers.map(reviewTierLine).join('\n')}\n`)
1032
+ const reader = resolveReader(config, process.env, process.platform)
1033
+ const tiers = reviewTierStack({ served: page, fileUrl: null, publishedUrl: null, config, reader })
1034
+ process.stdout.write(`page: ${humanLabel(window)}\n${reviewStackText(tiers)}`)
1032
1035
  return true
1033
1036
  }
1034
1037
 
@@ -1132,13 +1135,14 @@ function epicPageTiers(inputs, up, epic) {
1132
1135
  if (!inputs.config) return null
1133
1136
  if (!up) return { off: true, start: 'skitterspec spec-env review serve --host 0.0.0.0' }
1134
1137
  const served = reviewServedUrls(up, offerableLanAddresses(), epic)
1135
- return { tiers: reviewTierStack({ served, fileUrl: null, publishedUrl: null, config: inputs.config }) }
1138
+ const reader = resolveReader(inputs.config, process.env, process.platform)
1139
+ return { tiers: reviewTierStack({ served, fileUrl: null, publishedUrl: null, config: inputs.config, reader }) }
1136
1140
  }
1137
1141
 
1138
1142
  function epicPageLines(page) {
1139
1143
  if (!page) return ''
1140
1144
  if (page.off) return `epic page: no review server running — start it with: ${page.start}\n`
1141
- return `epic page:\n${page.tiers.map(reviewTierLine).join('\n')}\n`
1145
+ return `epic page:\n${reviewStackText(page.tiers)}`
1142
1146
  }
1143
1147
 
1144
1148
  // The working tree `--here` reads: the project folder of the checkout this
@@ -4874,7 +4878,8 @@ function reshowStack(dir, config, spec, out) {
4874
4878
  const cfg = withSpecRemote(config, out)
4875
4879
  const up = readRunningReviewServer(dir, cfg)
4876
4880
  const served = up ? reviewServedUrls(up, offerableLanAddresses(), spec.folder) : null
4877
- const tiers = reviewTierStack({ served, fileUrl: reviewFileUrl(out), publishedUrl: readReviewUrl(out), config: cfg })
4881
+ const reader = resolveReader(cfg, process.env, process.platform)
4882
+ const tiers = reviewTierStack({ served, fileUrl: reviewFileUrl(out), publishedUrl: readReviewUrl(out), config: cfg, reader })
4878
4883
  let live = null
4879
4884
  try {
4880
4885
  const primaryState = assertPrimaryOnMain(cfg, gitReader(dir))
@@ -4941,7 +4946,7 @@ async function specEnvReviewWait(dir, config, specArg, flags) {
4941
4946
  `${rearm ? ` (re-arm ${rearm})` : ''}\n` +
4942
4947
  (stack
4943
4948
  ? ` re-show: banner (re-arm ${rearm})\n` +
4944
- stack.tiers.map((t) => reviewTierLine(t) + '\n').join('') +
4949
+ reviewStackText(stack.tiers) +
4945
4950
  (liveStateLine(stack.live) ? `${liveStateLine(stack.live)}\n` : '')
4946
4951
  : ''),
4947
4952
  )
@@ -6212,7 +6217,7 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
6212
6217
  const url = readReviewUrl(out)
6213
6218
 
6214
6219
  // Resolved before the --json early return, so both outputs agree.
6215
- const reader = resolveReader(config, process.env)
6220
+ const reader = resolveReader(config, process.env, process.platform)
6216
6221
 
6217
6222
  // A remote reader cannot open a path on this machine — that is the whole of
6218
6223
  // what detection established. Serving is how the engine answers it: a local
@@ -6279,6 +6284,10 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
6279
6284
  }
6280
6285
  }
6281
6286
 
6287
+ // ONE STACK for both outputs, so `--json` and the text cannot disagree about
6288
+ // which tiers exist — or which one is hidden.
6289
+ const stackTiers = reviewTierStack({ served, fileUrl: reviewFileUrl(out), publishedUrl: url, config, reader })
6290
+
6282
6291
  if (flags.json) {
6283
6292
  process.stdout.write(
6284
6293
  JSON.stringify(
@@ -6305,12 +6314,10 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
6305
6314
  // The same stack the text prints, so a skill reads the tiers rather
6306
6315
  // than parsing prose — and the two can never disagree, because both
6307
6316
  // come from `reviewTierStack`.
6308
- tiers: reviewTierStack({
6309
- served,
6310
- fileUrl: reviewFileUrl(out),
6311
- publishedUrl: url,
6312
- config,
6313
- }),
6317
+ tiers: stackTiers,
6318
+ // Which served tiers one wait covers — the holding line's tiers, so a
6319
+ // banner never names a door the stack did not show.
6320
+ covers: waitCovers(stackTiers),
6314
6321
  // The same answer `live status --json` gives, from the same function,
6315
6322
  // so the page and the command cannot disagree. Always present, unlike
6316
6323
  // the tiers' optional keys: `unavailable` is a state a consumer needs
@@ -6432,19 +6439,12 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
6432
6439
  // rendering — `reviewTierLine` carries them, which is what puts them
6433
6440
  // under `network:` rather than dangling after the stack (they used to
6434
6441
  // print below `remote:`, against the comment that placed them).
6435
- reviewTierStack({
6436
- served,
6437
- fileUrl: reviewFileUrl(out),
6438
- publishedUrl: url,
6439
- config,
6440
- })
6441
- .map((t) => reviewTierLine(t) + '\n')
6442
- .join('') +
6442
+ reviewStackText(stackTiers) +
6443
6443
  // WHICH TIERS THE WAIT COVERS, once, next to the stack. `local` and
6444
6444
  // `network` are two doors into one room — the page POSTs to
6445
6445
  // `location.pathname`, so both reach this server and this pending store.
6446
6446
  // `remote` writes to the artifact's own store, which nothing here can see.
6447
- ' the wait covers local + network; a remote verdict needs /spec-reviewed.\n' +
6447
+ ` the wait covers ${waitCovers(stackTiers).join(' + ')}; a remote verdict needs /spec-reviewed.\n` +
6448
6448
  // WHETHER IT IS ALSO RUNNING SOMEWHERE, which is the other way to judge a
6449
6449
  // change. `unavailable` prints nothing — see `liveStateLine`.
6450
6450
  (liveStateLine(live) ? `${liveStateLine(live)}\n` : '') +
@@ -6506,6 +6506,10 @@ async function specEnvDev(dir, config, positional) {
6506
6506
  const out = [`spec-env dev up: ${spec.folder} slot ${slot} (ports from ${plan.portOffset})`]
6507
6507
  for (const proc of plan.procs) {
6508
6508
  const res = startProcess(proc, { cwd: spec.projectPath, rootDir: dir })
6509
+ if (res.error) {
6510
+ out.push(` ${proc.name}: port ${proc.port} NOT STARTED — ${res.error}`)
6511
+ continue
6512
+ }
6509
6513
  let health = ''
6510
6514
  if (proc.health) {
6511
6515
  health = (await waitHealthy(proc.health)) ? ' health: ok' : ' health: TIMEOUT'
@@ -6593,8 +6597,9 @@ function proxyProcFor(config, routesFileAbs) {
6593
6597
  const sdir = stateDirLabel(config)
6594
6598
  return {
6595
6599
  name: 'proxy',
6596
- // Quoted: this runs through `sh -c`, which eats a Windows path's
6597
- // backslashes and splits any path with a space (chore-windows-ci).
6600
+ // `argv` is what runs — node itself, no shell (bug-review-serve-spawn-sh).
6601
+ // `command` is the same thing for a person to read.
6602
+ argv: [process.execPath, path.join(__dirname, 'env', 'proxy.js'), routesFileAbs],
6598
6603
  command: `node ${shellPath(path.join(__dirname, 'env', 'proxy.js'))} ${shellPath(routesFileAbs)}`,
6599
6604
  env: {},
6600
6605
  logFile: `${sdir}/logs/proxy.log`,
@@ -6606,8 +6611,15 @@ function proxyProcFor(config, routesFileAbs) {
6606
6611
  // monorepo developing itself, and a project that installed the package. Naming
6607
6612
  // the distribution here is a path, not provider machinery — `init.js` and
6608
6613
  // `PROVIDER_COMMANDS` above already know package names by name.
6614
+ //
6615
+ // EVERY DISTRIBUTION, not only the base. A project installs exactly one, and a
6616
+ // superset missing here fell through to `__dirname` — the RUNNING copy — so a
6617
+ // worktree's engine saw the primary's server as executing a different script,
6618
+ // called it stale and stopped it (bug-review-serve-spawn-sh).
6609
6619
  const DAEMON_LOCATIONS = [
6610
- path.join('node_modules', '@skitterbyte', 'skitterspec', 'src', 'env', 'serve.js'),
6620
+ ...['skitterspec', 'skitterspec-linear', 'skitterspec-jira', 'skitterspec-github', 'skitterspec-azure-boards'].map(
6621
+ (pkg) => path.join('node_modules', '@skitterbyte', pkg, 'src', 'env', 'serve.js'),
6622
+ ),
6611
6623
  path.join('packages', 'common', 'src', 'env', 'serve.js'),
6612
6624
  ]
6613
6625
 
@@ -6663,8 +6675,10 @@ function serveProcFor(config, settingsFileAbs, { root = null } = {}) {
6663
6675
  const sdir = stateDirLabel(config)
6664
6676
  return {
6665
6677
  name: 'review-serve',
6666
- // Quoted: this runs through `sh -c`, which eats a Windows path's
6667
- // backslashes and splits any path with a space (chore-windows-ci).
6678
+ // `argv` is what runs — node itself, no shell. It used to go through
6679
+ // `sh -c`, and a Windows session without Git's bin on PATH has no `sh`
6680
+ // (bug-review-serve-spawn-sh). `command` is the same thing for a person.
6681
+ argv: [process.execPath, daemonScript(root), settingsFileAbs],
6668
6682
  command: `node ${shellPath(daemonScript(root))} ${shellPath(settingsFileAbs)}`,
6669
6683
  script: daemonScript(root),
6670
6684
  env: {},
@@ -6917,6 +6931,9 @@ async function ensureReviewServer(dir, config, { host = '127.0.0.1', port, resta
6917
6931
  ) + '\n',
6918
6932
  )
6919
6933
  const res = startProcess(proc, { cwd: dir, rootDir: dir })
6934
+ // Nothing was spawned, so there is nothing to wait for — and the reason is
6935
+ // the only thing worth handing back.
6936
+ if (res.error) return { error: `could not start the server (${res.error})`, port: usePort, replaced, engineWas }
6920
6937
  const up = await waitListening([usePort], { host: loopback ? host : '127.0.0.1' })
6921
6938
  // A PORT ANSWERING IS NOT PROOF THAT OUR PROCESS IS ANSWERING IT. `waitListening`
6922
6939
  // connects, and anything already bound satisfies a connect — so on its own it
@@ -7061,6 +7078,11 @@ async function specEnvReviewServe(dir, config, flags) {
7061
7078
  return
7062
7079
  }
7063
7080
 
7081
+ if (started.error) {
7082
+ process.stdout.write(`spec-env review serve: ${started.error} — see ${proc.logFile}\n`)
7083
+ return
7084
+ }
7085
+
7064
7086
  const { port, token, loopback } = started
7065
7087
  const res = { pid: started.pid }
7066
7088
 
package/src/env/review.js CHANGED
@@ -222,8 +222,13 @@ function numstatFor(git, ref, file, untracked) {
222
222
  * WHAT WOULD FOOL THIS: the bridge variable is an undocumented harness internal
223
223
  * and may be renamed or dropped, so its ABSENCE proves nothing — which is the
224
224
  * whole reason `unknown` exists and the default is not `local`.
225
+ *
226
+ * `platform` is passed in for the same reason as `env`, and defaults to NONE
227
+ * rather than `process.platform`: a caller that names no platform, and every
228
+ * test that states only an environment, gets the platform-free answer on any
229
+ * machine the suite runs on.
225
230
  */
226
- function detectReader(env = {}) {
231
+ function detectReader(env = {}, platform = null) {
227
232
  // SSH first: a standard convention, and the strongest available signal. If the
228
233
  // shell arrived over the network, the page's path is on a machine the reader
229
234
  // is not looking at.
@@ -233,6 +238,20 @@ function detectReader(env = {}) {
233
238
  // produced the original dead link, read on a phone.
234
239
  if (env.CLAUDE_CODE_BRIDGE_SESSION_ID) return { reader: 'remote', why: 'bridge session' }
235
240
 
241
+ // A WINDOWS SESSION WITH NO DESKTOP. Windows sets SESSIONNAME for every
242
+ // interactive logon — `Console` at the desktop, `RDP-Tcp#N` over Remote
243
+ // Desktop — and whatever starts from that desktop inherits it. A process
244
+ // outside any desktop has none: `prlctl exec`'s background logon (a Mac
245
+ // driving the VM), the OpenSSH server, a scheduled task, a service. Nobody is
246
+ // at this machine's browser in any of those.
247
+ //
248
+ // WHAT WOULD FOOL THIS: a scheduled task or service run while someone sits at
249
+ // the desk. That is affordable only because of what it decides — `local` is
250
+ // hidden only while `network` has a URL, and that URL is the same server, so
251
+ // a wrong guess costs the second-best link, never a page that will not open.
252
+ // Elsewhere SESSIONNAME means nothing, so its absence is not evidence.
253
+ if (platform === 'win32' && !env.SESSIONNAME) return { reader: 'remote', why: 'no interactive session' }
254
+
236
255
  // CLAUDE_CODE_ENTRYPOINT IS DELIBERATELY NOT CONSULTED. It describes the
237
256
  // PROCESS, not the reader, and reports `cli` for a bridged session — it said
238
257
  // exactly that for the session this was written from, where the reader was on
@@ -248,10 +267,38 @@ function detectReader(env = {}) {
248
267
  * sniffing: the operator knows where they are reading, and no signal outranks
249
268
  * being told.
250
269
  */
251
- function resolveReader(config, env = {}) {
270
+ function resolveReader(config, env = {}, platform = null) {
271
+ // THE WRAPPER FIRST, because it is the one thing that knows this machine. A
272
+ // committed `review.reader` speaks for every checkout of the repo; a wrapper
273
+ // that runs the engine inside a VM (`prlctl exec`) speaks for this one, and
274
+ // the VM shows nothing else to detect — no SSH, no session variables.
275
+ const told = String(env.SKITTERSPEC_READER || '').trim().toLowerCase()
276
+ if (told === 'local' || told === 'remote') return { reader: told, why: 'SKITTERSPEC_READER' }
252
277
  const setting = (config && config.review && config.review.reader) || 'detect'
253
278
  if (setting === 'local' || setting === 'remote') return { reader: setting, why: 'configured' }
254
- return detectReader(env)
279
+ return detectReader(env, platform)
280
+ }
281
+
282
+ /**
283
+ * Whether the reader's browser is on another machine, so `127.0.0.1` is the
284
+ * wrong one — the question that hides the `local` tier.
285
+ *
286
+ * NARROWER THAN `reader === 'remote'`, deliberately. A bridge session is a
287
+ * reader driving this session from elsewhere, but often from a browser on this
288
+ * same machine, where loopback opens fine; and its variable is an undocumented
289
+ * harness internal. Hiding a working link on that guess is the load-bearing
290
+ * detection `detectReader` warns against, so only the signals someone set on
291
+ * purpose count: the wrapper's variable, the committed setting, and SSH — plus
292
+ * one detection, a Windows session with no desktop, admitted because hiding
293
+ * `local` only ever happens beside a working `network` URL, so being wrong
294
+ * costs the second-best link rather than the loop.
295
+ *
296
+ * WHAT WOULD FOOL THIS: SSH with a `-L` port forward makes the reader's loopback
297
+ * reach this server, so `ssh` is a strong hint rather than proof —
298
+ * `SKITTERSPEC_READER=local` is the way back, and it outranks it.
299
+ */
300
+ function readerOffMachine(reader) {
301
+ return Boolean(reader && reader.reader === 'remote' && reader.why !== 'bridge session')
255
302
  }
256
303
 
257
304
  /**
@@ -721,7 +768,7 @@ function surfacesFor({ live, tiers, buttons = null }) {
721
768
  * pending store, and one wait covers both. `remote` is a second store, which is
722
769
  * why it carries the line saying so.
723
770
  */
724
- function reviewTierStack({ served, fileUrl, publishedUrl, config }) {
771
+ function reviewTierStack({ served, fileUrl, publishedUrl, config, reader = null }) {
725
772
  const tiers = []
726
773
  const loopbackUrl = served && served.loopbackUrl ? served.loopbackUrl : null
727
774
 
@@ -772,9 +819,46 @@ function reviewTierStack({ served, fileUrl, publishedUrl, config }) {
772
819
  tiers.push({ tier: 'remote', unavailable: true, note: 'publishing is an ask — nothing published yet' })
773
820
  }
774
821
 
822
+ // A READER ON ANOTHER MACHINE gets no `local` door: it points at this
823
+ // machine's loopback, so it hangs and never opens — first in the list, and
824
+ // the one habit reaches for. Hidden only when `network` has a URL to take
825
+ // its place; with none, an empty stack is worse than a dead link that says
826
+ // it is dead, so it stays and says so. Kept in `--json` either way, marked,
827
+ // so the decision is visible rather than an absence.
828
+ if (readerOffMachine(reader)) {
829
+ const network = tiers.find((t) => t.tier === 'network')
830
+ const why = `the reader is on another machine (${reader.why})`
831
+ tiers[0] =
832
+ network && network.url
833
+ ? { ...tiers[0], hidden: true, reason: why }
834
+ : { ...tiers[0], note: "not reachable from the reader's machine" }
835
+ }
836
+
775
837
  return tiers
776
838
  }
777
839
 
840
+ /**
841
+ * The stack as printed text: every tier the reader can use, one line each,
842
+ * each ending in a newline. A `hidden` tier prints nothing — it is in `--json`
843
+ * for anyone who asks, and absent from the screen a reader clicks from.
844
+ */
845
+ function reviewStackText(tiers) {
846
+ return tiers
847
+ .filter((t) => !t.hidden)
848
+ .map((t) => reviewTierLine(t) + '\n')
849
+ .join('')
850
+ }
851
+
852
+ /**
853
+ * The served tiers one wait covers, as the stack shows them. `local` and
854
+ * `network` are two doors into one room; with `local` hidden there is one door,
855
+ * and the line must not name one the reader was never shown.
856
+ */
857
+ function waitCovers(tiers) {
858
+ const local = tiers.find((t) => t.tier === 'local')
859
+ return local && local.hidden ? ['network'] : ['local', 'network']
860
+ }
861
+
778
862
  // One tier as a line, padded so the labels form a column the eye can run down.
779
863
  // A tier with alternates renders them as indented `also:` lines of its own —
780
864
  // they are PART of the tier, which is what puts them under `network:` rather
@@ -2632,6 +2716,8 @@ module.exports = {
2632
2716
  surfacesFor,
2633
2717
  reviewTierStack,
2634
2718
  reviewTierLine,
2719
+ reviewStackText,
2720
+ waitCovers,
2635
2721
  isTailnetAddress,
2636
2722
  tailnetLabel,
2637
2723
  COMMITTING,
@@ -2724,6 +2810,7 @@ module.exports = {
2724
2810
  renderReviewFragment,
2725
2811
  detectReader,
2726
2812
  resolveReader,
2813
+ readerOffMachine,
2727
2814
  CHECK_LEVELS,
2728
2815
  loadTemplate,
2729
2816
  TEMPLATE_PATH,
@@ -32,7 +32,7 @@ const fs = require('node:fs')
32
32
  const path = require('node:path')
33
33
  const crypto = require('node:crypto')
34
34
  const { spawn } = require('node:child_process')
35
- const { signalGroup } = require('./supervise.js')
35
+ const { signalGroup, resolveShell } = require('./supervise.js')
36
36
 
37
37
  const BUNDLED_ADAPTERS = { coderabbit: require('./reviewers/coderabbit.js') }
38
38
 
@@ -288,9 +288,10 @@ function runReviewer(entry, ctx) {
288
288
  // Through a shell, deliberately: the config holds a command LINE, with
289
289
  // pipes and quoting the project chose. It is read from a committed config
290
290
  // in the project's own repo — the same trust level as a package script.
291
- // `sh` from PATH on Windows — Git for Windows' — where `/bin/sh` does not
292
- // exist and no reviewer could run at all (chore-windows-ci).
293
- child = spawnFn(process.platform === 'win32' ? 'sh' : '/bin/sh', ['-c', rendered], {
291
+ // Git for Windows' `sh` on Windows, where `/bin/sh` does not exist and no
292
+ // reviewer could run at all (chore-windows-ci) — found off PATH too, and
293
+ // left as a bare `sh` to fail as `did not run` when there is none.
294
+ child = spawnFn(process.platform === 'win32' ? resolveShell() || 'sh' : '/bin/sh', ['-c', rendered], {
294
295
  cwd: worktree,
295
296
  stdio: ['ignore', 'pipe', 'pipe'],
296
297
  // THE CHILD LEADS ITS OWN PROCESS GROUP, and the timeout below depends
@@ -67,11 +67,48 @@ function readPid(pidFileAbs) {
67
67
  }
68
68
  }
69
69
 
70
+ /**
71
+ * The shell a planned `command` runs through, or null when there is none.
72
+ *
73
+ * POSIX: `sh` from PATH, as it always was. Windows: `sh` only exists where Git
74
+ * for Windows put its `bin` on PATH, and a `cmd /c` session (a VM driven from
75
+ * another host, a scheduled task) commonly has Git installed and not on PATH.
76
+ * So PATH first, then Git's own install locations, then the `bin` beside a
77
+ * `git.exe` that IS on PATH (`Git\cmd\git.exe` → `Git\bin\sh.exe`).
78
+ *
79
+ * WHAT WOULD FOOL THIS: Git installed somewhere none of those name — a scoop
80
+ * shim, a portable copy. Then the answer is null, and the caller refuses with
81
+ * a reason rather than spawning something that is not there.
82
+ */
83
+ function resolveShell({ platform = process.platform, env = process.env, exists = fs.existsSync } = {}) {
84
+ if (platform !== 'win32') return 'sh'
85
+ const w = path.win32
86
+ const dirs = String(env.PATH || env.Path || '').split(';').filter(Boolean)
87
+ const candidates = dirs.map((d) => w.join(d, 'sh.exe'))
88
+ for (const base of [env.ProgramFiles, env.ProgramW6432, env['ProgramFiles(x86)']]) {
89
+ if (base) candidates.push(w.join(base, 'Git', 'bin', 'sh.exe'))
90
+ }
91
+ if (env.LOCALAPPDATA) candidates.push(w.join(env.LOCALAPPDATA, 'Programs', 'Git', 'bin', 'sh.exe'))
92
+ for (const d of dirs) {
93
+ if (exists(w.join(d, 'git.exe'))) candidates.push(w.join(d, '..', 'bin', 'sh.exe'))
94
+ }
95
+ return candidates.find((c) => exists(c)) || null
96
+ }
97
+
70
98
  /**
71
99
  * Start one planned process detached, appending stdout+stderr to its log and
72
100
  * writing its pid file. Idempotent: if the pid file already names a live
73
101
  * process, nothing is spawned — returns `{ started: false, pid }`.
74
102
  *
103
+ * A proc carrying `argv` is spawned as exactly that, with no shell — the review
104
+ * server and the proxy are `node <script> <file>` and never needed one. A proc
105
+ * carrying only `command` runs through `resolveShell`.
106
+ *
107
+ * NEVER THROWS OVER A SPAWN THAT FAILED. A missing executable is reported as
108
+ * `{ started: false, pid: null, error }` with no pid file written: the ENOENT
109
+ * otherwise arrives as an unhandled 'error' event and takes the CLI down with
110
+ * it (bug-review-serve-spawn-sh).
111
+ *
75
112
  * `spawnImpl` is injectable for tests; defaults to child_process.spawn.
76
113
  */
77
114
  function startProcess(proc, { cwd, rootDir, spawnImpl = spawn }) {
@@ -83,19 +120,44 @@ function startProcess(proc, { cwd, rootDir, spawnImpl = spawn }) {
83
120
  return { started: false, pid: existing, logFile: logAbs, pidFile: pidAbs }
84
121
  }
85
122
 
123
+ const env = { ...process.env, ...proc.env }
124
+ let file
125
+ let args
126
+ if (proc.argv) {
127
+ ;[file, ...args] = proc.argv
128
+ } else {
129
+ file = resolveShell({ env })
130
+ args = ['-c', proc.command]
131
+ if (!file) {
132
+ const error = 'no sh found — install Git for Windows or put its bin folder on PATH'
133
+ return { started: false, pid: null, error, logFile: logAbs, pidFile: pidAbs }
134
+ }
135
+ }
136
+
86
137
  fs.mkdirSync(path.dirname(logAbs), { recursive: true })
87
138
  fs.mkdirSync(path.dirname(pidAbs), { recursive: true })
88
139
 
89
140
  const out = fs.openSync(logAbs, 'a')
90
141
  try {
91
- const child = spawnImpl('sh', ['-c', proc.command], {
92
- cwd,
93
- env: { ...process.env, ...proc.env },
94
- detached: true,
95
- // No console window per dev server on Windows; nothing anywhere else.
96
- windowsHide: true,
97
- stdio: ['ignore', out, out],
98
- })
142
+ let child
143
+ try {
144
+ child = spawnImpl(file, args, {
145
+ cwd,
146
+ env,
147
+ detached: true,
148
+ // No console window per dev server on Windows; nothing anywhere else.
149
+ windowsHide: true,
150
+ stdio: ['ignore', out, out],
151
+ })
152
+ } catch (err) {
153
+ return { started: false, pid: null, error: `spawn ${file}: ${err.message}`, logFile: logAbs, pidFile: pidAbs }
154
+ }
155
+ // A spawn that could not start has no pid, and its error is emitted on the
156
+ // next tick — the listener is what keeps that from being fatal.
157
+ child.on('error', () => {})
158
+ if (!child.pid) {
159
+ return { started: false, pid: null, error: `could not start ${file}`, logFile: logAbs, pidFile: pidAbs }
160
+ }
99
161
  child.unref()
100
162
  fs.writeFileSync(pidAbs, `${child.pid}\n`)
101
163
  return { started: true, pid: child.pid, logFile: logAbs, pidFile: pidAbs }
@@ -167,4 +229,4 @@ async function waitHealthy(
167
229
  // therefore kills the wrapper, leaves the server holding its port, and then
168
230
  // blames whatever it asserts next. Killing the group is what `stopProcess` does
169
231
  // and what a test must do to mean "it died".
170
- module.exports = { startProcess, stopProcess, waitHealthy, isAlive, readPid, signalGroup }
232
+ module.exports = { startProcess, stopProcess, waitHealthy, isAlive, readPid, signalGroup, resolveShell }