@bongos/core 1.20.13 → 1.20.15

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.15",
+  "core_contract": "1.20.15",
+  "source_commit": "139b563191ef97af7e538f783d3fb256baa6c075",
   "source_ref": "HEAD",
-  "built_at": "2026-09-30T11:48:47.948Z",
+  "built_at": "2026-09-30T12:16:56.172Z",
   "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": "814cbc7e5df7346b441a3ac6faa4217852105b51708505d98b9e090d68bd8b6a",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2772,7 +2772,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "a0725bf013ddc823d06b866f5008497dddf1bf63e2e22852cd6eb79525ce5052"
+      "sha256": "05833e301ee659bde426bdae2d327183b03a6e40b08230a07ce99ba8ccef9705"
     },
     {
       "path": "docs/modules-contract.md",
@@ -2882,7 +2882,7 @@
     {
       "path": "docs/recipes/autobongos-windows-host.md",
       "mode": "0000644",
-      "sha256": "566cf83d1f58fb41d211e9db7cd7d616ae4c2186f1b308baef805ad112bc9aab"
+      "sha256": "e70faa969725827307388ccb0620bde203500333ed299d860ca7a001cc8577a1"
     },
     {
       "path": "docs/recipes/bongos-cli-release.md",
@@ -8862,12 +8862,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "09eb2f9f11cdcb5cb24ccddee43c9d09d5e1135a452e0827542ea96d70b2e85f"
+      "sha256": "cc8381c4866cb96ae92e56199b4666a515f8c4fb6aa0214fe332a2c960f5c9df"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "c80938c396a4982970d0850791d002ea2f5c49b93c8e75f6066c33c77bc7ae78"
+      "sha256": "5125b2ece4cbf29c1c89b0eec97b4bce224fa0b25c8b3351e0b6253ade41c8e5"
     },
     {
       "path": "public-docs/index.html",
@@ -8887,7 +8887,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "a3de1adc96eea0bd98814403baf635fc2523506d45ca0df0ae263c917b324757"
+      "sha256": "d12e72f6946fb8c0884d7b014d8673e58314ad5ff4d01593d397f5d96d8c8a6e"
     },
     {
       "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": "b1e038bb70ace1652b85a4d29f5a68761c6b432fd50fbfdafb5e1e38d93627de"
     },
     {
       "path": "scripts/gds/autobongos-verify.js",
@@ -11002,7 +11002,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "20017aec62763445738eeed4b8c1d23cbe6789a77223992022cb4c9e7747111c"
+      "sha256": "d97c483c3599928877210a4ceea2c9a384cf61dc86d1fec156de8a95dce743e5"
     },
     {
       "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": "34ca7d75bc83d9c4a77706dd06ecc170011ef52b7ee77eea5c3b77ac514389d0"
+    },
     {
       "path": "tests/autobongos_verify.mjs",
       "mode": "0000644",

package/docs/module-api-changelog.md

@@ -2683,5 +2683,9 @@ 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)
+  1.20.15 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.20.14 with no explicit bump. run 36713710510. (task 1002620)
 ---------------------------------------------------------------------------
 ```

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

@@ -18,7 +18,7 @@ Task [1003905](https://cloudbongos.com/builders#/task/1003905).
 
 ## What you need on the box first
 
-Open PowerShell as your normal user (not Administrator) and check all three:
+Open PowerShell as your own user and check all three:
 
 ```powershell
 node --version ; git --version ; claude --version
@@ -28,7 +28,7 @@ All three must print a version. The installer refuses to proceed otherwise —
 a runner that starts without `claude` on its PATH fails every worker and looks
 like a mysterious outage in the log rather than a missing program.
 
-You also need, as **your own user** (not an administrator account):
+You also need, as **your own user** (not a separate administrator account):
 
 - a `git` credential that can fetch the repo,
 - a signed-in Claude Code session,
@@ -53,13 +53,29 @@ machine can write, the worker running on it can write too.
 
 ## 2. Install the scheduled task
 
-From the checkout:
+**This step, and only this step, needs an Administrator shell.** Right-click
+PowerShell, choose **Run as administrator**, and sign in to the prompt as the
+**same user** you checked the prerequisites with — then, from the checkout:
 
 ```powershell
 powershell -ExecutionPolicy Bypass -File scripts\gds\autobongos-service.ps1 install
 powershell -ExecutionPolicy Bypass -File scripts\gds\autobongos-service.ps1 start
 ```
 
+Why admin, when the runner deliberately is not: two different things happen
+here. **Registering** the task needs admin, because it uses the S4U logon type
+(run whether or not anyone is signed in), and Windows only lets an elevated
+shell register one — from a normal shell `install` stops and says so, rather
+than failing with a bare *Access is denied*. **Running** the task does not: it
+runs as you, unelevated (`-RunLevel Limited`), which is what lets it use your
+git credential and Claude session. Elevating the same account keeps your
+username, so the task is still registered to run as you.
+
+Do **not** install it as SYSTEM, or from a different administrator account:
+the task would run as that account, which has none of your credentials. If
+your own account is not an administrator on this PC, make it one for the
+install rather than elevating as someone else.
+
 That registers a task called `Autobongos` that starts **at boot** (not at sign-in
 — nobody should have to log in), restarts if it crashes, and never times out.
 
@@ -134,8 +150,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.15",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.20.13",
+      "version": "1.20.15",
       "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.15",
   "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,21 @@
       "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."
+    }
+  ],
+  "1.20.15": [
+    {
+      "id": "1004177",
+      "text": "Installing the Windows runner now tells you up front that it needs an administrator window, and why, instead of failing with a bare \"access denied\"; the setup guide no longer says the opposite."
+    }
   ]
 }

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

@@ -25,7 +25,8 @@
 # UNPRIVILEGED ON PURPOSE. It runs as the logged-in user, not SYSTEM: the runner
 # needs that user's git credential, npm config and Claude session, and SYSTEM has
 # none of them. It is also the smaller blast radius for a process that spawns
-# workers with blanket bypassPermissions.
+# workers with blanket bypassPermissions. (INSTALLING it is the one step that
+# needs an elevated shell of that same user -- see Assert-Prereqs, task 1004177.)
 
 [CmdletBinding()]
 param(
@@ -49,10 +50,32 @@ $LogDir = Join-Path $env:LOCALAPPDATA 'cloudbongos'
 $LogFile = Join-Path $LogDir 'autobongos.log'
 $Wrapper = Join-Path $RepoRoot 'scripts\gds\autobongos-service.cmd'
 
+# Is this shell elevated (Run as administrator)? Its own function so the tests
+# can stand it in: the check is Windows-only, and CI runs on Linux.
+function Test-Elevated {
+  $id = [Security.Principal.WindowsIdentity]::GetCurrent()
+  return ([Security.Principal.WindowsPrincipal]$id).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)
+}
+
+# REGISTERING vs RUNNING (task 1004177). The task RUNS as this user, unelevated
+# (-RunLevel Limited): that is what reaches the user's git credential and Claude
+# session, and it is load-bearing. But REGISTERING a task with an S4U principal
+# needs an elevated shell -- unelevated, Register-ScheduledTask fails with a bare
+# "Access is denied" (0x80070005) that says nothing about why. Elevating the SAME
+# account keeps $env:USERNAME, so the principal below is still this user. So
+# install -- and only install -- checks, and says so in words, before trying.
+$ElevationNeeded = @(
+  'install needs an elevated shell: registering a task that runs whether or not you are signed in (the S4U logon type) requires Administrator.',
+  'Open PowerShell with "Run as administrator" AS THIS SAME USER and run install again. The task still RUNS as you, unelevated (-RunLevel Limited) -- only the registration needs admin.',
+  'Do NOT install it as SYSTEM or another admin account: the runner needs your git credential and Claude session, and SYSTEM has neither.'
+) -join ' '
+
 function Assert-Prereqs {
+  param([switch]$ForInstall)
   if (-not (Test-Path (Join-Path $RepoRoot 'scripts\gds\autobongos-run.js'))) {
     throw "No autobongos-run.js under $RepoRoot -- pass -RepoRoot <path to the checkout>."
   }
+  if ($ForInstall -and -not (Test-Elevated)) { throw $ElevationNeeded }
   foreach ($exe in @('node', 'git', 'claude')) {
     if (-not (Get-Command $exe -ErrorAction SilentlyContinue)) {
       # Named, not guessed at: a runner that starts without `claude` on PATH will
@@ -84,9 +107,114 @@ 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
+    Assert-Prereqs -ForInstall
     New-Item -ItemType Directory -Force -Path $LogDir | Out-Null
 
     # NOT $action: PowerShell variable names are CASE-INSENSITIVE, so $action IS the
@@ -131,10 +259,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.15'; // 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,206 @@
+// 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);
+});
+
+// --- install needs an elevated shell, and says why (task 1004177) -------------
+//
+// Registering an S4U task needs Administrator; unelevated, Register-ScheduledTask
+// throws a bare "Access is denied". The recipe used to say the opposite. Test-
+// Elevated is stood in (it is Windows-only), everything else is the real script.
+// The stub runs AFTER the dot-source, so it replaces the script's own definition.
+
+const assertPrereqs = (elevated, args) =>
+  `function Test-Elevated { $${elevated} }; ` +
+  `try { Assert-Prereqs ${args}; 'PASSED' } catch { 'THREW=' + $_.Exception.Message }`;
+
+test('install from an unelevated shell is refused with the reason, not a bare access-denied', { skip }, async () => {
+  const r = await ps(assertPrereqs('false', '-ForInstall'));
+  assert.match(r.out, /THREW=install needs an elevated shell/, r.out);
+  assert.match(r.out, /S4U/);
+  assert.match(r.out, /Run as administrator/);
+  assert.match(r.out, /SAME USER/, 'elevating the same account is what keeps the principal right');
+  assert.match(r.out, /still RUNS as you, unelevated/);
+  assert.match(r.out, /Do NOT install it as SYSTEM/);
+});
+
+test('an elevated shell passes the elevation check', { skip }, async () => {
+  const r = await ps(assertPrereqs('true', '-ForInstall'));
+  // It may still stop on a later prereq (a CI runner has no `claude`), but
+  // never on elevation.
+  assert.doesNotMatch(r.out, /elevated shell/, r.out);
+});
+
+test('only install asks for elevation', { skip }, async () => {
+  const r = await ps(assertPrereqs('false', ''));
+  assert.doesNotMatch(r.out, /elevated shell/, r.out);
+});
+
+test('the install arm runs the install-only check', () => {
+  const live = readFileSync(PS1, 'utf8').split(/\r?\n/).map((l) => l.replace(/#.*$/, '')).join('\n');
+  const installArm = live.slice(live.indexOf("'install' {"), live.indexOf("'uninstall' {"));
+  assert.match(installArm, /Assert-Prereqs -ForInstall/);
+  assert.ok(installArm.indexOf('Assert-Prereqs -ForInstall') < installArm.indexOf('Register-ScheduledTask'),
+    'the check must run before the registration it explains');
+});
+
+test('the recipe says install needs Administrator, and why, and not SYSTEM', () => {
+  const doc = readFileSync(fileURLToPath(new URL('../docs/recipes/autobongos-windows-host.md', import.meta.url)), 'utf8');
+  assert.doesNotMatch(doc, /normal user \(not Administrator\)/, 'the instruction that made install fail');
+  const install = doc.slice(doc.indexOf('## 2. Install the scheduled task'), doc.indexOf('## 3.'));
+  assert.match(install, /Run as administrator/);
+  assert.match(install, /S4U/);
+  assert.match(install, /same (user|account)/i);
+  assert.match(install, /SYSTEM/);
+  assert.match(install, /-RunLevel Limited/);
+});