@bongos/core 1.20.13 → 1.20.14

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.20.13",
-  "core_contract": "1.20.13",
-  "source_commit": "1e8134c4bbd7d8623139bfd31ba2701c5bf120ac",
+  "core_version": "1.20.14",
+  "core_contract": "1.20.14",
+  "source_commit": "791ad29beab00019cab69c01896dbb132b40b5ad",
   "source_ref": "HEAD",
-  "built_at": "2026-09-30T11:48:47.948Z",
+  "built_at": "2026-09-30T12:05:40.305Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 556,
     "agent_docs_stubbed": 25,
-    "functional_verbatim": 2626,
+    "functional_verbatim": 2628,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 3208,
-  "tree_sha256": "ae284b5e2f56e08cb0b29b13e77a015dc35db8f5be3a99a96a731704c7da0053",
+  "file_count": 3210,
+  "tree_sha256": "521479f97c392987b24cca51bd5ca57048b353ae978e89f748a15793d8e80990",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2772,7 +2772,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "a0725bf013ddc823d06b866f5008497dddf1bf63e2e22852cd6eb79525ce5052"
+      "sha256": "b3abd2f21a34a8547f169368ddcaa19364e2fcb5f5ddeb4f296bcfaf67acf3b5"
     },
     {
       "path": "docs/modules-contract.md",
@@ -2882,7 +2882,7 @@
     {
       "path": "docs/recipes/autobongos-windows-host.md",
       "mode": "0000644",
-      "sha256": "566cf83d1f58fb41d211e9db7cd7d616ae4c2186f1b308baef805ad112bc9aab"
+      "sha256": "e8c45b5b1ab16fc5ae7bbfaef677672f338195dde885e734d53d752c5113deeb"
     },
     {
       "path": "docs/recipes/bongos-cli-release.md",
@@ -8862,12 +8862,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "09eb2f9f11cdcb5cb24ccddee43c9d09d5e1135a452e0827542ea96d70b2e85f"
+      "sha256": "908c96be621ea531a175e213836861eddf3bd3b652f793aaefd6fd098d7e5543"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "c80938c396a4982970d0850791d002ea2f5c49b93c8e75f6066c33c77bc7ae78"
+      "sha256": "88ae8247e31afb3b9e49258788fe2f01132af4779ba70f3377ca6b8af3756adf"
     },
     {
       "path": "public-docs/index.html",
@@ -8887,7 +8887,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "a3de1adc96eea0bd98814403baf635fc2523506d45ca0df0ae263c917b324757"
+      "sha256": "4d06b7011b86e611f4ae20cd9f925c3a27715663139ceb06d4b3f841a8c764f0"
     },
     {
       "path": "scripts/bongos-mcp.js",
@@ -9047,7 +9047,7 @@
     {
       "path": "scripts/gds/autobongos-run.js",
       "mode": "0000644",
-      "sha256": "5467681b59e569c4d7fccd4ed6ea93cd598a26ddd2fd42c384375f37ae0243ea"
+      "sha256": "c8e6967fe75be8573e65c1fd73caec6912aeb75648dfdb3c82a04cd7bc7f6a6d"
     },
     {
       "path": "scripts/gds/autobongos-service.cmd",
@@ -9057,7 +9057,7 @@
     {
       "path": "scripts/gds/autobongos-service.ps1",
       "mode": "0000644",
-      "sha256": "ed95f836655535827c14a32caf197fee7c238e15d8e8bf7a9e987b78ab266887"
+      "sha256": "2dcf13abd58dfaf6cce56285dc1f156efe06be9e2307acc0d9e2bc7912c9f424"
     },
     {
       "path": "scripts/gds/autobongos-verify.js",
@@ -11002,7 +11002,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "20017aec62763445738eeed4b8c1d23cbe6789a77223992022cb4c9e7747111c"
+      "sha256": "111c9b37716e607675072df7499f9040e048c7b6f5e4c006890d4b898dc6c9d3"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -11437,18 +11437,28 @@
     {
       "path": "tests/autobongos_cadence.mjs",
       "mode": "0000644",
-      "sha256": "32ad1726b5af44707dde1d01425bf6435671685ab8077185e8ee83a6d7ef248a"
+      "sha256": "98f86c0f7cb84ecfe955f74a066326d82e8af1008c17d0a28c0ad40042f876b8"
     },
     {
       "path": "tests/autobongos_fence.mjs",
       "mode": "0000644",
       "sha256": "00709f1c010f594c457b9bdb49bd0d7377cebdb140e080869a8f7458960841ff"
     },
+    {
+      "path": "tests/autobongos_heartbeat_head.mjs",
+      "mode": "0000644",
+      "sha256": "f750e0978dc811420e61ac2ae7be4abd896631447c47004b1ab662e742ec3ac3"
+    },
     {
       "path": "tests/autobongos_loop.mjs",
       "mode": "0000644",
       "sha256": "e14d2c211c28ebada8e915d0d336989e74410afb68924d9b89dc8efd666457c8"
     },
+    {
+      "path": "tests/autobongos_service_ps1.mjs",
+      "mode": "0000644",
+      "sha256": "541a3030ed91fe74b98b837e4d45b59e6a337b9f45c99f848a9df53a20b781a1"
+    },
     {
       "path": "tests/autobongos_verify.mjs",
       "mode": "0000644",

package/docs/module-api-changelog.md

@@ -2683,5 +2683,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.20.11 with no explicit bump. run 36709211337. (task 1002620)
   1.20.13 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.20.12 with no explicit bump. run 36710762884. (task 1002620)
+  1.20.14 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.20.13 with no explicit bump. run 36712510525. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/recipes/autobongos-windows-host.md

@@ -134,8 +134,16 @@ Use the **kill switch in the hall**, not the scheduled task. The switch survives
 a reboot and cannot be undone by anything running on the machine; stopping the
 task only stops this run, and the next boot starts it again.
 
-`autobongos-service.ps1 stop` exists for maintenance on the box itself and says
-this when you use it.
+`autobongos-service.ps1 stop` exists for maintenance on the box itself. It asks
+Task Scheduler to stop the task, then **watches the runner's own process** (the
+pid in its heartbeat file) and tells you which of these happened:
+
+| It says | Means |
+|---|---|
+| `stopped ... has exited` | the process was watched to exit. The next boot starts it again |
+| `NOT STOPPED ... still running after Ns` | the process outlived the stop (exit code 1). It runs under a different logon session (S4U) that a normal shell cannot end — `Stop-Process` fails the same way. From an **Administrator** PowerShell run the `taskkill /F /PID <pid>` it prints, or reboot. Until then `start` does nothing, because the task will not launch a second copy over a live one |
+| `was not running` | the heartbeat's process had already exited |
+| `CANNOT CONFIRM` | there is no heartbeat pid to check; look with `Get-Process node` |
 
 ## Keeping the checkout current
 

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.20.13",
+  "version": "1.20.14",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.20.13",
+      "version": "1.20.14",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.20.13",
+  "version": "1.20.14",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/release-notes.json

@@ -8130,5 +8130,15 @@
       "id": "1004180",
       "text": "When the unattended runner fails to pick up a task, its log now always says why, starting with the sentence that explains it, instead of an empty line or a fragment cut off mid-word."
     }
+  ],
+  "1.20.14": [
+    {
+      "id": "1004375",
+      "text": "Stopping the Windows runner now checks that it really stopped, and when it could not, says so and tells you exactly how to finish the job."
+    },
+    {
+      "id": "1004397",
+      "text": "The unattended runner now records which version of the code it is running from its very first check-in, instead of leaving that blank for its first minute, which is exactly when someone is trying to find out."
+    }
   ]
 }

package/scripts/gds/autobongos-run.js

@@ -876,6 +876,14 @@ async function forever(opts, deps = {}) {
     try { beatFile(); } catch (_) { /* a runner that cannot write its file still runs */ }
     try { await beatServer(fields, deps); } catch (_) { /* and one that cannot reach the instance still runs */ }
   };
+  // The running commit, read ONCE, BEFORE the first beat (task 1004397). It used
+  // to be read lazily by codeDrifted(), which sits behind the one-minute uptime
+  // floor, so every beat in a process's first minute said head:null — the window
+  // in which a crash-looping or repeatedly-restarted runner is being looked at.
+  // The floor exists to stop a restart STORM, not to avoid this read: one local
+  // rev-parse. Fails soft to null inside loadedHead(), and a null is retried by
+  // the drift check later, so an unreadable head never stops the runner.
+  try { await (deps.loadedHead ? deps.loadedHead(deps) : loadedHead(deps)); } catch (_) { /* head stays null */ }
   await beat({ last_event: 'boot' });
 
   // BEFORE ANY WORK. A claim left locked by a previous run is the worst thing

package/scripts/gds/autobongos-service.ps1

@@ -84,6 +84,111 @@ function Show-Status {
   Write-Host 'is actually working is the hall: it reads the heartbeat this posts.'
 }
 
+# --- stop, and say what actually happened (task 1004375) -----------------------
+#
+# Stop-ScheduledTask returns as soon as the scheduler has been ASKED. It does not
+# wait, and it does not report whether the process went away -- and on the host
+# it did not: the runner, started under the S4U logon type, sat in a session the
+# interactive user could not terminate, survived Stop-ScheduledTask AND a
+# Stop-Process -Force, while this script printed "stopped". Because the task is
+# MultipleInstances IgnoreNew, a following `start` then no-ops against the old
+# process, and the pair reads as a clean restart that changed nothing.
+#
+# So 'stop' now reads the runner's own pid from the heartbeat it writes
+# (autobongos-run.js writeHeartbeat -> <config dir>\autobongos-heartbeat.json),
+# asks the scheduler to stop, POLLS for that pid to exit, and reports one of four
+# outcomes. It never says "stopped" about a process it has not watched exit.
+
+# Where the runner writes its heartbeat: asked of the RUNNER, via its own
+# exported heartbeatPath(), not re-derived here. That function is the only
+# definition -- AUTOBONGOS_HEARTBEAT_FILE first, then the branding pack's config
+# dir, then the repo root -- and a second copy of it in PowerShell would drift
+# from the file the runner actually writes, which is the exact bug this fixes.
+# Only if node itself cannot answer does this fall back to the repo-root name.
+function Get-HeartbeatFile {
+  $fromRunner = $null
+  try {
+    $run = Join-Path $RepoRoot 'scripts\gds\autobongos-run.js'
+    $fromRunner = & node -e "process.stdout.write(String(require(process.argv[1]).heartbeatPath()))" $run
+  } catch { $fromRunner = $null }
+  if ($fromRunner) { return [string]$fromRunner }
+  return (Join-Path $RepoRoot '.autobongos-heartbeat.json')
+}
+
+# The pid the runner recorded, or $null when there is no file or no usable pid.
+function Read-RunnerPid([string]$HeartbeatFile) {
+  if (-not $HeartbeatFile -or -not (Test-Path $HeartbeatFile)) { return $null }
+  try { $hb = Get-Content -Raw -Path $HeartbeatFile | ConvertFrom-Json } catch { return $null }
+  $n = 0
+  if ($hb -and [int]::TryParse([string]$hb.pid, [ref]$n) -and $n -gt 0) { return $n }
+  return $null
+}
+
+# Alive AND node: a heartbeat left behind by a crash can name a pid that Windows
+# has since handed to some unrelated process, and that must not read as "the
+# runner is still running".
+function Test-RunnerAlive([int]$ProcessId) {
+  $p = Get-Process -Id $ProcessId -ErrorAction SilentlyContinue
+  return [bool]($p -and $p.ProcessName -eq 'node')
+}
+
+# Outcome is one of:
+#   stopped        -- the pid was alive, and was watched to exit
+#   still_running  -- the pid was alive and is STILL alive after the wait
+#   not_running    -- the heartbeat's pid was already gone before the stop
+#   unknown        -- no pid to check, so nothing can be claimed either way
+# StopTask is injectable so tests/autobongos_service_ps1.mjs can drive the real
+# polling against a real process without a scheduled task.
+function Invoke-RunnerStop {
+  param(
+    [string]$HeartbeatFile,
+    [int]$TimeoutSeconds = 20,
+    [scriptblock]$StopTask = { Stop-ScheduledTask -TaskName $TaskName }
+  )
+  $runnerPid = Read-RunnerPid $HeartbeatFile
+  $wasAlive = [bool]($runnerPid -and (Test-RunnerAlive $runnerPid))
+  & $StopTask
+  if (-not $runnerPid) { return [pscustomobject]@{ Outcome = 'unknown'; Pid = $null; Waited = 0 } }
+  if (-not $wasAlive) { return [pscustomobject]@{ Outcome = 'not_running'; Pid = $runnerPid; Waited = 0 } }
+  $started = Get-Date
+  $deadline = $started.AddSeconds($TimeoutSeconds)
+  while ((Test-RunnerAlive $runnerPid) -and ((Get-Date) -lt $deadline)) { Start-Sleep -Milliseconds 250 }
+  $waited = [int][math]::Round(((Get-Date) - $started).TotalSeconds)
+  $outcome = if (Test-RunnerAlive $runnerPid) { 'still_running' } else { 'stopped' }
+  return [pscustomobject]@{ Outcome = $outcome; Pid = $runnerPid; Waited = $waited }
+}
+
+function Format-StopReport($Result, [string]$HeartbeatFile) {
+  $p = $Result.Pid
+  switch ($Result.Outcome) {
+    'stopped' {
+      "stopped '$TaskName' -- runner pid $p has exited (watched, not assumed)."
+      'That is for now only: the next boot starts it again. To keep the runner from'
+      'working, use the kill switch in the hall (/builders/gate) -- it survives a'
+      'reboot and nothing running on this machine can undo it.'
+    }
+    'still_running' {
+      "NOT STOPPED: asked Task Scheduler to stop '$TaskName', but runner pid $p is still running after $($Result.Waited)s."
+      'It may be under a different logon session (the task runs as S4U), which this'
+      'shell cannot end -- Stop-Process from here fails the same way.'
+      "Remedy: from an elevated (Administrator) PowerShell run   taskkill /F /PID $p"
+      'or reboot the machine. Until it exits, `start` does nothing: the task will not'
+      'launch a second copy over a live one (MultipleInstances IgnoreNew).'
+    }
+    'not_running' {
+      "'$TaskName' was not running: runner pid $p from the heartbeat had already exited."
+    }
+    default {
+      "asked Task Scheduler to stop '$TaskName', but CANNOT CONFIRM the runner exited:"
+      "no runner pid in $HeartbeatFile. Check   Get-Process node   before assuming it stopped."
+    }
+  }
+}
+
+# Dot-sourced (the tests do this to reach the functions above), stop here: the
+# switch below is the command-line entry point and must not run on a load.
+if ($MyInvocation.InvocationName -eq '.') { return }
+
 switch ($Action) {
   'install' {
     Assert-Prereqs
@@ -131,10 +236,12 @@ switch ($Action) {
   }
   'start'  { Start-ScheduledTask -TaskName $TaskName; Write-Host "started '$TaskName'" }
   'stop'   {
-    Stop-ScheduledTask -TaskName $TaskName
-    Write-Host "stopped '$TaskName' -- but note this only stops the PROCESS on this machine."
-    Write-Host 'The durable way to stop the runner is the kill switch in the hall, which'
-    Write-Host 'survives a reboot and cannot be undone by anything running here.'
+    $hbFile = Get-HeartbeatFile
+    $result = Invoke-RunnerStop -HeartbeatFile $hbFile
+    Format-StopReport $result $hbFile | ForEach-Object { Write-Host $_ }
+    # Non-zero when the process outlived the stop, so a script driving this
+    # (a restart, a maintenance step) cannot carry on as if it had worked.
+    if ($result.Outcome -eq 'still_running') { exit 1 }
   }
   default  { Show-Status }
 }

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.20.13'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.20.14'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');

package/tests/autobongos_cadence.mjs

@@ -277,6 +277,9 @@ function loopHarness({ rows, maxLoops = 6 }) {
     // Declaring no drift keeps each test about the one thing it is testing;
     // tests/autobongos_loop.mjs covers the drift exit itself.
     codeDrifted: async () => false,
+    // forever() reads the running commit at startup (task 1004397); answered here
+    // rather than by a real git call, for the same reason as the beats above.
+    loadedHead: async () => null,
   };
   return { deps, waits: emitted, recorded, opts: { goals: [], maxTasks: 3, maxLoops } };
 }

package/tests/autobongos_heartbeat_head.mjs

@@ -0,0 +1,75 @@
+// tests/autobongos_heartbeat_head.mjs — the FIRST heartbeat carries the commit
+// the process is running (task 1004397).
+//
+// The heartbeat's `head` exists so "alive" can be told apart from "alive but
+// running week-old code" (task 1004374). It was filled lazily, via codeDrifted(),
+// which sits behind the one-minute uptime floor — so every beat in a process's
+// first minute said head:null. That is exactly the window someone is looking in
+// when a runner crash-loops, or keeps being restarted to pick up a fix.
+//
+// ITS OWN FILE ON PURPOSE. The running head is cached in a module-level variable
+// (read once per process, by design), and node:test gives each file its own
+// process. In a shared file an earlier test that reached loadedHead() would
+// already have filled the cache, and the "first beat has a head" case would pass
+// for a reason unrelated to the fix. The two tests below also depend on their
+// ORDER for the same reason: the unreadable case runs first, while the cache is
+// still empty.
+//
+// MINIMUM INJECTION: writeHeartbeat and loadedHead are NOT injected — the real
+// ones run, as they do under main(). Only the outward calls are stubbed: run()
+// (so git is answered, not executed), the server beat, and the loop's own
+// collaborators.
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ab-head-'));
+process.env.AUTOBONGOS_HEARTBEAT_FILE = path.join(dir, 'beat.json');
+process.env.AUTOBONGOS_LOG_FILE = path.join(dir, 'runs.jsonl');
+
+const runner = require('../scripts/gds/autobongos-run.js');
+
+const SHA = 'abcdef0123456789abcdef0123456789abcdef01';
+
+function deps(run, seen) {
+  return {
+    run,
+    // Read the file at the moment the boot beat has been written and nothing
+    // else has run yet: reconcile is the next step after it.
+    reconcileLeftoverClaims: async () => { seen.push(runner.readHeartbeat()); return { event: 'boot_reconcile', ok: true, leftover: 0 }; },
+    iteration: async () => ({ event: 'nothing_claimable', skipped: [] }),
+    waitOrJump: async () => ({ waited: 0, jumped: false }),
+    postHeartbeat: async () => true,
+    codeDrifted: async () => false,
+    record: (r) => r,
+    emit: () => {},
+  };
+}
+
+test('an unreadable head leaves head null and never stops the runner', async () => {
+  const seen = [];
+  const run = async () => ({ ok: false, code: 128, stdout: '', stderr: 'fatal: not a git repository' });
+  const code = await runner.forever({ goals: [], maxTasks: 1, maxLoops: 1 }, deps(run, seen));
+  assert.equal(code, 0);
+  assert.equal(seen[0].pid, process.pid);
+  assert.equal(seen[0].head, null, 'cannot-tell is written as null, not as a guess');
+});
+
+test('the FIRST heartbeat a process writes carries the commit it is running', async () => {
+  const seen = [];
+  const calls = [];
+  const run = async (bin, args) => {
+    calls.push(args.join(' '));
+    return args[0] === 'rev-parse' ? { ok: true, code: 0, stdout: SHA + String.fromCharCode(10), stderr: '' } : { ok: false, code: 1, stdout: '', stderr: '' };
+  };
+  await runner.forever({ goals: [], maxTasks: 1, maxLoops: 1 }, deps(run, seen));
+  assert.equal(seen[0].head, SHA, 'the boot beat — inside the uptime floor — must already name the commit');
+  assert.ok(calls.includes('rev-parse HEAD'), 'read from git, once, at startup');
+  assert.equal(await runner.loadedHead(), SHA, 'and cached: the drift check later compares against the same read');
+});

package/tests/autobongos_service_ps1.mjs

@@ -0,0 +1,154 @@
+// tests/autobongos_service_ps1.mjs — the Windows host installer's own behaviour
+// (scripts/gds/autobongos-service.ps1).
+//
+// task 1004375: `stop` printed "stopped" while the runner kept running. The
+// runner, started under the S4U logon type, sat in a session the interactive user
+// could not end, so Stop-ScheduledTask asked, returned, and the script reported
+// success without ever checking. These cases drive the REAL stop logic — dot-
+// sourced out of the script, against a real node process whose pid is in a real
+// heartbeat file — with only the scheduler call injected, because there is no
+// scheduled task to stop on a test runner.
+//
+// Needs a PowerShell. Windows ships `powershell`; the ubuntu CI image ships
+// `pwsh`. In CI a missing shell FAILS rather than skips: a suite that quietly
+// skips where it is gated is a suite that rots green.
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { spawn, spawnSync } from 'node:child_process';
+import { mkdtempSync, writeFileSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+const PS1 = fileURLToPath(new URL('../scripts/gds/autobongos-service.ps1', import.meta.url));
+
+function findShell() {
+  for (const bin of ['pwsh', 'powershell']) {
+    const r = spawnSync(bin, ['-NoProfile', '-NonInteractive', '-Command', '$PSVersionTable.PSVersion.Major'], { encoding: 'utf8' });
+    if (r.status === 0) return bin;
+  }
+  return null;
+}
+const SHELL = findShell();
+if (!SHELL && process.env.CI) throw new Error('no PowerShell (pwsh/powershell) on this CI runner — these cases must run, not skip');
+const skip = SHELL ? false : 'no PowerShell on this machine';
+
+const tmp = mkdtempSync(path.join(tmpdir(), 'abs-ps1-'));
+process.on('exit', () => { try { rmSync(tmp, { recursive: true, force: true }); } catch (_) {} });
+
+// Dot-source the script, then run `body`. Single quotes inside PS literals are
+// doubled; every path handed in goes through q().
+//
+// ASYNC ON PURPOSE. On Linux a killed child stays a zombie -- still listed by
+// Get-Process, still named node -- until its parent reaps it, and node reaps only
+// while its event loop runs. A spawnSync here would block that loop for the whole
+// PowerShell run, so a fake runner the case kills would never leave the process
+// table and a correct stop would read as still_running. Windows has no zombies,
+// which is why a spawnSync first cut passed there and failed on the ubuntu image.
+const q = (s) => `'${String(s).replace(/'/g, "''")}'`;
+function ps(body, extraEnv = {}) {
+  const script = `$ErrorActionPreference = 'Stop'; . ${q(PS1)}; ${body}`;
+  return new Promise((resolve) => {
+    const c = spawn(SHELL, ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', script], {
+      // The script's top level joins LOCALAPPDATA, which a Linux runner lacks.
+      env: { ...process.env, LOCALAPPDATA: process.env.LOCALAPPDATA || tmp, ...extraEnv },
+      timeout: 60_000,
+    });
+    let out = '';
+    c.stdout.on('data', (d) => { out += d; });
+    c.stderr.on('data', (d) => { out += d; });
+    c.on('close', (status) => resolve({ status, out }));
+  });
+}
+
+// A stand-in runner: a real, long-lived node process, and a heartbeat naming it
+// the way autobongos-run.js writeHeartbeat does.
+function fakeRunner(name) {
+  const child = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)'], { stdio: 'ignore' });
+  const hb = path.join(tmp, `${name}.json`);
+  writeFileSync(hb, JSON.stringify({ pid: child.pid, at: new Date().toISOString(), head: 'abc' }));
+  return { child, hb, pid: child.pid };
+}
+const report = (hb, stopTask, timeout = 2) =>
+  `$r = Invoke-RunnerStop -HeartbeatFile ${q(hb)} -TimeoutSeconds ${timeout} -StopTask { ${stopTask} }; ` +
+  `Format-StopReport $r ${q(hb)} | ForEach-Object { $_ }; 'OUTCOME=' + $r.Outcome`;
+
+test('a stop that leaves the process running says so, and names the pid and the remedy', { skip }, async () => {
+  // The host's case exactly: the scheduler call returns and the process stays.
+  const { child, hb, pid } = fakeRunner('survivor');
+  try {
+    const r = await ps(report(hb, '<# the scheduler asked; nothing died #>'));
+    assert.equal(r.status, 0, r.out);
+    assert.match(r.out, /OUTCOME=still_running/, r.out);
+    assert.doesNotMatch(r.out, /^stopped/m, 'must never claim a stop it did not see');
+    assert.match(r.out, /NOT STOPPED/);
+    assert.match(r.out, new RegExp(`runner pid ${pid} is still running after \\d+s`));
+    assert.match(r.out, /different logon session/);
+    assert.match(r.out, new RegExp(`taskkill /F /PID ${pid}`), 'the remedy names the actual pid');
+    assert.match(r.out, /elevated/);
+    assert.match(r.out, /reboot/);
+  } finally { child.kill(); }
+});
+
+test('a stop that ends the process is watched to exit before it says "stopped"', { skip }, async () => {
+  const { child, hb, pid } = fakeRunner('ends');
+  try {
+    const r = await ps(report(hb, `Stop-Process -Id ${pid} -Force`, 10));
+    assert.equal(r.status, 0, r.out);
+    assert.match(r.out, /OUTCOME=stopped/, r.out);
+    assert.match(r.out, new RegExp(`stopped 'Autobongos' -- runner pid ${pid} has exited`));
+    // The caveat is about the NEXT boot, not a hedge on whether this stop worked.
+    assert.match(r.out, /next boot starts it again/);
+    assert.match(r.out, /kill switch/);
+  } finally { child.kill(); }
+});
+
+test('no pid to check means no claim either way', { skip }, async () => {
+  const r = await ps(report(path.join(tmp, 'absent.json'), ''));
+  assert.match(r.out, /OUTCOME=unknown/, r.out);
+  assert.match(r.out, /CANNOT CONFIRM/);
+  assert.doesNotMatch(r.out, /^stopped/m);
+});
+
+test('a heartbeat pid now held by a NON-node process is not "the runner still running"', { skip }, async () => {
+  // A crash leaves the file behind and Windows reuses pids. The PowerShell's own
+  // $PID is alive and is not node: that must read as already gone.
+  const hb = path.join(tmp, 'reused.json');
+  const r = await ps(`Set-Content -Path ${q(hb)} -Value ('{"pid":' + $PID + '}'); ${report(hb, '')}`);
+  assert.match(r.out, /OUTCOME=not_running/, r.out);
+  assert.doesNotMatch(r.out, /NOT STOPPED/);
+});
+
+test('the command-line stop exits non-zero when the process survived', () => {
+  // Structural half: the entry point must route through the checked stop and
+  // fail loudly on still_running, so a restart script cannot carry on as if it
+  // worked. Comments are stripped so a commented-out line cannot satisfy it.
+  const live = readFileSync(PS1, 'utf8').split(/\r?\n/).map((l) => l.replace(/#.*$/, '')).join('\n');
+  const stopArm = live.slice(live.indexOf("'stop'   {"));
+  assert.match(stopArm, /Invoke-RunnerStop/);
+  assert.match(stopArm, /still_running'\)\s*\{\s*exit 1\s*\}/);
+  assert.doesNotMatch(live, /Write-Host "stopped '\$TaskName' -- but note/, 'the old unchecked claim is gone');
+});
+
+
+// The pid is only as good as the FILE it is read from. stop must look where the
+// runner writes, so Get-HeartbeatFile asks the runner's own heartbeatPath() --
+// these pin that the two agree, including its first-precedence env override.
+const runner = createRequire(import.meta.url)('../scripts/gds/autobongos-run.js');
+
+test('stop reads the heartbeat file the runner itself writes', { skip }, async () => {
+  const saved = process.env.AUTOBONGOS_HEARTBEAT_FILE;
+  delete process.env.AUTOBONGOS_HEARTBEAT_FILE;
+  const expected = runner.heartbeatPath();
+  if (saved !== undefined) process.env.AUTOBONGOS_HEARTBEAT_FILE = saved;
+  const r = await ps("'HB=' + (Get-HeartbeatFile)", { AUTOBONGOS_HEARTBEAT_FILE: '' });
+  assert.equal(path.resolve(r.out.match(/HB=(.*)/)[1].trim()), path.resolve(expected), r.out);
+});
+
+test('stop honours AUTOBONGOS_HEARTBEAT_FILE exactly as the runner does', { skip }, async () => {
+  const override = path.join(tmp, 'override-heartbeat.json');
+  const r = await ps("'HB=' + (Get-HeartbeatFile)", { AUTOBONGOS_HEARTBEAT_FILE: override });
+  assert.equal(path.resolve(r.out.match(/HB=(.*)/)[1].trim()), path.resolve(override), r.out);
+});