@plot-pm/board 0.14.0 → 0.14.1

package/plot-host.sh

@@ -834,6 +834,47 @@ jenkins_no_instance() {
 # estimate for. This draws it one step earlier, for a connector that does not
 # exist at all — and `resultOf` (`adapters/run-script.ts:211`) maps exit 4 onto
 # `unaskable`, which is the word the build port already answers with.
+# The Jenkins REST credential, read from where `jen` already stores it.
+#
+# NOT THE KEYCLOAK BEARER. `jen auth token` prints one and Jenkins answers it
+# with an HTML login redirect — measured 2026-09-10, and it is the trap that
+# made an earlier reading conclude the sha was unreachable. Jenkins' own API
+# takes BASIC auth with a user and an API token, which `jen` keeps in the login
+# keychain under service `jen`, accounts `jenkins-user:<host>` and
+# `jenkins-token:<host>`.
+#
+# IT PRINTS `user:token` AND NOTHING ELSE, or nothing at all. The caller passes
+# it straight to `curl -u`; no branch echoes it, and no failure path names it.
+#
+# EMPTY IS THE HONEST ANSWER on a machine with no `security` (Linux, CI), with
+# no keychain entry, or with either half missing — a half credential is not a
+# credential. The caller turns that into exit 4, which is *cannot be asked*.
+jenkins_rest_credential() { # $1 = the bare host
+  command -v security >/dev/null 2>&1 || return 1
+  local u t
+  u=$(security find-generic-password -s jen -a "jenkins-user:$1" -w 2>/dev/null) || return 1
+  t=$(security find-generic-password -s jen -a "jenkins-token:$1" -w 2>/dev/null) || return 1
+  [ -n "$u" ] && [ -n "$t" ] || return 1
+  printf '%s:%s' "$u" "$t"
+}
+
+# A job path as Jenkins' REST API spells it: every segment under `job/`.
+#
+# `quaweb/release` is the path a person writes and `job/quaweb/job/release` is
+# the URL, because a Jenkins folder is itself a job. A multibranch branch adds
+# one more segment, PERCENT-ENCODED — `bug/foo` is `bug%2Ffoo`, the same
+# encoding `jenkins_build_map` already decodes on the way back.
+jenkins_job_url_path() { # $1 = job path, $2 = branch or ""
+  local out="" seg
+  local IFS=/
+  for seg in $1; do [ -n "$seg" ] && out="$out/job/$seg"; done
+  unset IFS
+  if [ -n "${2:-}" ]; then
+    out="$out/job/$(printf '%s' "$2" | sed 's|/|%2F|g')"
+  fi
+  printf '%s' "$out"
+}
+
 ci_unaskable() { # $1 = the op's name, $2 = the CI word (may be empty)
   local ci_word="${2:-}"
   if [ -z "$ci_word" ] || [ "$ci_word" = none ]; then
@@ -1722,12 +1763,47 @@ backend_declared() {
     return
   fi
   local v
-  v="$(bash "$here/plot-config.sh" get "Git host" "github" | tr '[:upper:]' '[:lower:]')"
+  v="$(bash "$here/plot-config.sh" get "Git host" "" | tr '[:upper:]' '[:lower:]')"
   case "$v" in
-    bb) echo "bitbucket" ;;
-    "") echo "github" ;;
-    *) printf '%s\n' "$v" ;;
+    bb) echo "bitbucket"; return ;;
+    "") : ;;
+    *) printf '%s\n' "$v"; return ;;
   esac
+
+  # NOTHING DECLARED — INFER FROM THE REMOTE, AND REFUSE WHERE THERE IS NONE.
+  # This answered `github` unconditionally until 2026-09-11, which is the
+  # reassuring direction: a Bitbucket repo that forgot the key got GitHub's
+  # answer, and a repo with no remote at all got one too. Measured on a fresh
+  # `git init` with no remote: `backend` printed `github` and exited 0.
+  #
+  # THE REMOTE IS EVIDENCE AND THE KEY IS A DECLARATION, so the key still wins
+  # above. What changes is only the case where nobody said: a hostname in the
+  # remote is a reading, and no remote is no reading.
+  local url
+  url="$(git config --get remote.origin.url 2>/dev/null || true)"
+  case "$url" in
+    *github.com*)    echo "github";    return ;;
+    *bitbucket.org*) echo "bitbucket"; return ;;
+  esac
+
+  # NOTHING NAMES A HOST, AND THAT IS REPORTED RATHER THAN REFUSED. An earlier
+  # version of this returned exit 4 here, and five contract tests went red:
+  # a sandbox repository with no remote is a legitimate, common shape — six
+  # suites build one — and every op that needs a host in one was relying on
+  # this default. Refusing at the resolver punishes them for a question they
+  # never asked.
+  #
+  # SO THE GUESS SURVIVES AND STOPS BEING SILENT — AND IT SIGNALS THROUGH THE
+  # EXIT CODE, NEVER A VARIABLE. This set a `BACKEND_UNNAMED` global first, and
+  # the caller reads it as `v="$(backend_declared)"` — a COMMAND SUBSTITUTION,
+  # which runs in a subshell, so the assignment died with the child and the
+  # parent always read 0. The warning never printed, and a direct call looked
+  # correct because its stdout was right.
+  #
+  # Exit 9 is arbitrary and deliberately outside the contract's 0/1/3/4: it
+  # never leaves this file, and `backend` maps it back to a successful answer.
+  echo "github"
+  return 9
 }
 
 # The resolved backend, refused where this script has no arm for it.
@@ -1740,12 +1816,27 @@ backend_declared() {
 # person must fix. `host-shell.ts` reads that code as `unaskable` and reads the
 # sentence below for the name.
 backend() {
-  local v
-  v="$(backend_declared)" || return 1
+  local v rc unnamed=0
+  # THE DECLARED-HOST REFUSAL IS PASSED THROUGH, NOT FLATTENED. `|| return 1`
+  # collapsed exit 4 into 1 here, and 4 is the one code every caller reads as
+  # *this cannot be asked at all* rather than *retry*. Measured 2026-09-11: a
+  # repository with no remote exited 1, which tells a caller to try again.
+  v="$(backend_declared)"; rc=$?
+  # 9 is the resolver's private word for *answered, but nothing named it*.
+  if [ "$rc" -eq 9 ]; then unnamed=1; rc=0; fi
+  [ "$rc" -eq 0 ] || return "$rc"
   if ! host_drivable "$v"; then
     echo "plot-host: cannot drive '$v' — this script drives ${HOST_DRIVES// /, }; set the 'Git host' key in CLAUDE.md (or \$PLOT_HOST) to one of them" >&2
     return 4
   fi
+  # THE ANSWER IS PRINTED EITHER WAY, AND A GUESS SAYS SO. `backend` is a
+  # reading, not a gate: a caller that needs a host still gets one, and a
+  # person asking which host this is learns the answer was inferred from
+  # nothing. Exit stays 0 — the value is usable, its provenance is not certain.
+  if [ "$unnamed" = 1 ]; then
+    echo "plot-host: no 'Git host' key and no remote names one — assuming '$v'" >&2
+    echo "  Set the 'Git host' key in ## Plot Config (or \$PLOT_HOST) to be sure." >&2
+  fi
   printf '%s\n' "$v"
 }
 
@@ -2991,29 +3082,100 @@ case "$op" in
     _ci="$(ci_scheme)"
     case "$_ci" in
       jenkins)
-        # JENKINS CANNOT ANSWER THIS THROUGH `jen`, AND THAT IS A MEASUREMENT
-        # RATHER THAN A GAP LEFT OPEN. `jenkins_build_map` — the only Jenkins
-        # reader this script has — answers `{color, checks, job}` per BRANCH and
-        # carries no commit at all, so there is nothing here to match a sha
-        # against.
+        # THE SHA IS IN JENKINS AND `jen` IS NOT THE TRANSPORT. Measured
+        # 2026-09-10 against a live instance: a build entry from `jen build
+        # list --json` carries `id`, `status`, timings and stages, and a search
+        # of the whole payload for `sha|commit|revision|scm` matches nothing.
+        # `jen` has no changesets subcommand and no raw-API passthrough.
+        #
+        # JENKINS' OWN REST API ANSWERS IT, at
+        # `actions[].lastBuiltRevision.SHA1`, paired with the branch. One
+        # `tree=` query returns a whole history — 4855 bytes for five builds —
+        # so this costs one round trip like the GitHub arm does.
+        #
+        # THIS ARM EXITED 4 UNTIL 2026-09-11, and the refusal was honest for
+        # the transport it had. What changed is the transport, not the rule.
+        _jen_instance="$(jenkins_instance)"
+        [ -n "$_jen_instance" ] || jenkins_no_instance
+        _jen_host="${_jen_instance%%/*}"
+        _jen_job="${_jen_instance#*/}"
+        [ "$_jen_job" = "$_jen_instance" ] && _jen_job=""
+        [ -n "${PLOT_JENKINS_JOB:-}" ] && _jen_job="$PLOT_JENKINS_JOB"
+        if [ -z "$_jen_job" ]; then
+          # A bare-host instance names no job, and a sha lives in a job's
+          # builds. `runs` degrades to an empty map here; this op has no row to
+          # carry that, so the only way to say *cannot be asked* is exit 4.
+          echo "plot-host: run-for-sha — the Jenkins instance names no job path" >&2
+          echo "  A sha is a fact about a job's builds, so the instance must be" >&2
+          echo "  <slug>/<job/path> rather than a bare host." >&2
+          exit 4
+        fi
+        _jen_cred="$(jenkins_rest_credential "$_jen_host")" || {
+          # NO CREDENTIAL IS *CANNOT BE ASKED*, never *no run*. The keychain is
+          # macOS-only and a Linux agent legitimately has none; saying nothing
+          # at exit 0 would read as a branch that never built.
+          echo "plot-host: run-for-sha — no Jenkins API credential for '$_jen_host'" >&2
+          echo "  Jenkins' REST API takes basic auth with an API token, which" >&2
+          echo "  \`jen auth login\` stores in the login keychain. The Keycloak" >&2
+          echo "  bearer from \`jen auth token\` is NOT it — Jenkins answers that" >&2
+          echo "  with a login redirect." >&2
+          exit 4
+        }
+        # A BRANCH IS A JOB SEGMENT ON A MULTIBRANCH JOB AND NOT ON A PLAIN
+        # ONE, and no reading of the configured path says which this is. So the
+        # multibranch URL is tried first and the plain one is the fallback:
+        # `job/quaweb/job/continuous-build/job/content%2Fctas` against
+        # `job/quaweb/job/release`. Measured 2026-09-11 — asking the plain job
+        # for a branch segment answers 404, which is why guessing one shape
+        # cost a run.
         #
-        # THE ANSWER EXISTS AND THIS TRANSPORT DOES NOT REACH IT. Measured
-        # 2026-09-08 against a live instance, a build names its commit at
-        # `actions[].BuildData.lastBuiltRevision.SHA1`, paired with its branch —
-        # over the REST API, which `the-ci-connector-is-jenkins` reads. Until
-        # that lands, `unaskable` is the true word: this connector cannot be
-        # asked, which is not the same as the branch having no run for the sha.
+        # THE PLAIN JOB REPORTS ITS OWN BUILDS whatever branch was asked about,
+        # and that is honest rather than wrong: a pipeline job builds one
+        # thing, and the `sha` in the answer says which commit it built.
+        _jen_tree="tree=builds%5Bnumber,result,building,timestamp,url,actions%5BlastBuiltRevision%5BSHA1%5D%5D%5D%7B0,$limit%7D"
+        _jen_body=""
+        for _jen_path in \
+          "$(jenkins_job_url_path "$_jen_job" "$branch")" \
+          "$(jenkins_job_url_path "$_jen_job" "")"; do
+          host_slot_take jenkins ''
+          _jen_try=$(curl -sg --max-time 30 -u "$_jen_cred" \
+            "https://$_jen_host$_jen_path/api/json?$_jen_tree" 2>/dev/null) || true
+          host_slot_give
+          budget_record_call jenkins ''
+          if printf '%s' "$_jen_try" | jq -e 'has("builds")' >/dev/null 2>&1; then
+            _jen_body="$_jen_try"; break
+          fi
+        done
+        _jen_cred=""
+        if [ -z "$_jen_body" ] || ! printf '%s' "$_jen_body" | jq -e 'has("builds")' >/dev/null 2>&1; then
+          # AN UNREACHABLE INSTANCE IS NOT AN EMPTY HISTORY. A refused or
+          # redirected request answers HTML, which fails the `builds` test.
+          echo "plot-host: run-for-sha — Jenkins did not answer for '$_jen_host'" >&2
+          exit 4
+        fi
+        # THE SAME FALLBACK RULE AS THE GITHUB ARM, and it is inherited rather
+        # than invented: the asked-for sha if a build carries it, else the
+        # newest build, and `sha` says WHICH. A caller that could not tell the
+        # two apart would be back to the branch-scoped guessing this op ends.
         #
-        # FALLING BACK TO THE BRANCH'S CURRENT STATE WOULD BE THE ONE ANSWER
-        # THAT COSTS A MERGE. This op exists because a run for a superseded
-        # commit reads identically to a run for the current one, and reporting
-        # a branch-scoped state with no sha in it is exactly the guessing it was
-        # written to end — two merge waiters were stopped for it on 2026-08-30.
-        echo "plot-host: run-for-sha — jenkins has no sha-scoped answer through \`jen\`" >&2
-        echo "  \`jen job list\` reports one state per branch and names no commit." >&2
-        echo "  A build's sha is in Jenkins and reached over its REST API, which" >&2
-        echo "  the Jenkins build connector reads. Until then this cannot be asked." >&2
-        exit 4
+        # `result` is null while a build runs, which is Jenkins' own word for
+        # *in flight* — mapped to the `status`/`conclusion` split the contract
+        # already uses, so the shape does not fork per connector.
+        printf '%s' "$_jen_body" | jq -c --arg sha "$sha" '
+          [ .builds[]
+            | { sha: ([ .actions[]? | select(.lastBuiltRevision) | .lastBuiltRevision.SHA1 ] | first // ""),
+                status: (if .building then "in_progress" else "completed" end),
+                conclusion: (if .building then null else (.result // null) end),
+                url: (.url // ""),
+                startedAt: (if .timestamp then (.timestamp / 1000 | todate) else "" end) } ]
+          | ((map(select(.sha == $sha)) | .[0]) // .[0])
+          | select(. != null)' 2>/dev/null || true
+        # THIS ARM ANSWERS AND THE OP IS OVER. Everything below the `esac` is
+        # the GitHub path — the old jenkins arm reached it only because it
+        # ended in `exit 4`. Measured 2026-09-11: without this the answer was
+        # printed and then a `CI is github-actions but the git host is
+        # 'bitbucket'` refusal followed it on stderr.
+        exit 0
         ;;
       github-actions) : ;;
       *) ci_unaskable run-for-sha "$_ci" ;;

package/plot-worker-state.sh

@@ -489,6 +489,140 @@ plot_worker_cpu_centis() { # $1=pid → total CPU centiseconds of pid+descendant
     }'
 }
 
+# The name a live agent's process carries, as a substring of its command.
+#
+# CONFIGURABLE BECAUSE THE AGENT IS THE PROJECT'S, NOT PLOT'S. Principle 5 —
+# Plot hardcodes no tooling — and the `Worker command` key already says every
+# project names its own. This is the default because it is what this estate
+# runs; a project whose agent is a different binary sets `PLOT_AGENT_PROCESS`
+# and nothing else changes.
+: "${PLOT_AGENT_PROCESS:=claude}"
+
+# Whether an AGENT — not merely the wrapper — is alive under this pid.
+#
+# THE DEFECT THIS ANSWERS. The pid this fleet records is the loop shell, and
+# `kill -0` on it succeeds for the whole `Worker bound` (28800 s) whether or not
+# an agent still runs inside it. Measured 2026-09-11, in one session: FOUR
+# agents ended mid-slice, none failed a build, none wrote a marker, and every
+# one reported `running` with a plausible quiet time. Three left 8 commits and 9
+# uncommitted files on their desks — one step from done, and all three would
+# have been reaped as abandoned.
+#
+# EXISTENCE, NOT MOTION, AND THAT IS THE WHOLE DISTINCTION FROM THE CUE BELOW.
+# `plot_worker_activity` samples CPU twice and asks whether the subtree is
+# MOVING; an agent blocked on a network read is `idle` and perfectly alive. This
+# asks whether there is an agent in the subtree AT ALL, which is a set
+# membership test over one snapshot rather than a delta over two. The cue may
+# never decide liveness, and this may never be read as a cue.
+#
+# ACCUMULATED CPU CANNOT DECIDE IT EITHER. Measured 2026-09-12 on this machine,
+# a dead agent's tree held three `bash` children at 0:41.50, 0:41.22 and
+# 0:40.31 — forty seconds of CPU each, burnt before the agent died. Only the
+# PRESENCE of the agent process separates that tree from a live one.
+#
+# THE SAME ONE-SNAPSHOT WALK `plot_worker_cpu_centis` USES, and for its reason:
+# a `pgrep -P` recursion forks a process per descendant on a scan the board
+# polls every 5 s. It is also the only shape that reaches the real depth —
+# measured on a healthy agent the same day, `claude` sat THREE levels below the
+# recorded pid (`sh` → `bash` → `bash` → `claude`), so a depth-limited probe
+# reports every live agent absent.
+#
+# ABSENT IS NOT FALSE, the rule this file keeps re-learning. A pid naming no
+# process at all returns 2 — *could not look* — rather than 1, because a failure
+# to observe is not evidence of something to see. The caller has already
+# established the pid answers `kill -0` before it asks this.
+# How long a wrapper must have been alive before its empty subtree means
+# anything.
+#
+# THE STARTUP WINDOW IS REAL AND IT IS THIS READING'S OWN. `kill -0` succeeds
+# the instant the wrapper exists, and the agent is forked some time after that —
+# measured 2026-09-12, 37 to 237 ms for a `sh` forking a trivial child, and a
+# real agent boots in seconds. A reading taken inside that window sees a worker
+# that is STARTING and would call it stopped.
+#
+# The file already documents the same hazard one level down: *"There is a
+# sub-millisecond window after the wrapper starts and before `.plot-worker.pid`
+# is written, and a scan landing in it reads `none` — honest."* That window is
+# tolerable because `none` tells a reader to look again; this one is not, because
+# the whole point of the reading is to let something ACT on a stopped agent, and
+# acting on a starting one hands its desk away as it boots.
+#
+# THIRTY SECONDS, AND IT IS A GUESS SAID OUT LOUD. Nothing has measured how long
+# an agent takes to appear under its wrapper on a loaded machine; this is an
+# order of magnitude above the worst observed fork and an order below the
+# shortest slice. It is overridable so the tests need not wait, and a project on
+# slower hardware can raise it.
+: "${PLOT_AGENT_GRACE_SECONDS:=30}"
+
+# The whole seconds a pid has been alive, or empty when it cannot be read.
+#
+# `etime` RATHER THAN `lstart`, because this needs a DURATION and `lstart` is a
+# date a caller would have to parse and subtract. `[[DD-]HH:]MM:SS` is parsed
+# from the right, the way `plot_worker_cpu_centis` parses its clock and for the
+# same reason: an absolute-seconds assumption wraps at 60.
+plot_pid_elapsed_seconds() { # $1=pid → whole seconds, or empty
+  local pid="$1" raw
+  [ -n "$pid" ] || return 1
+  raw=$(ps -o etime= -p "$pid" 2>/dev/null | tr -d ' ') || return 1
+  [ -n "$raw" ] || return 1
+  printf '%s' "$raw" | awk '
+    {
+      n = split($0, dh, "-")
+      days = (n == 2) ? dh[1] : 0
+      t = (n == 2) ? dh[2] : dh[1]
+      m = split(t, p, ":")
+      total = 0; mult = 1
+      for (i = m; i >= 1; i--) { total += p[i] * mult; mult *= 60 }
+      print total + (days * 86400)
+    }'
+}
+
+plot_worker_agent_alive() { # $1=pid → 0 agent present, 1 absent, 2 unaskable
+  local root="$1" age
+  [ -n "$root" ] || return 2
+  case "$root" in *[!0-9]*) return 2 ;; esac
+
+  # A WRAPPER YOUNGER THAN THE GRACE IS UNASKABLE, NEVER ABSENT. It may be
+  # starting its agent right now, and `2` is the answer that says *could not
+  # look* — which the callers already resolve to today's behaviour. Absent is
+  # not false, and a failure to observe is not evidence of something to see.
+  age=$(plot_pid_elapsed_seconds "$root") || age=""
+  if [ -n "$age" ] && [ "$age" -lt "$PLOT_AGENT_GRACE_SECONDS" ] 2>/dev/null; then
+    return 2
+  fi
+
+  # `comm=` IS THE EXECUTABLE, `command=` IS THE WHOLE INVOCATION, and this
+  # needs the second. A wrapper whose argv merely NAMES the agent would match on
+  # `command=`, so the match is anchored to the executable's own basename —
+  # taken from `comm=`, which macOS truncates but never rewrites.
+  ps -o pid=,ppid=,comm= -ax 2>/dev/null | awk -v root="$root" -v want="$PLOT_AGENT_PROCESS" '
+    { pid[$1] = $1; ppid[$1] = $2
+      # Everything after pid and ppid is the command; keep its basename.
+      c = $0; sub(/^[ \t]*[0-9]+[ \t]+[0-9]+[ \t]+/, "", c)
+      sub(/.*\//, "", c)
+      comm[$1] = c }
+    END {
+      if (!(root in pid)) { exit 2 }
+      # The same relaxation the CPU walker uses: sweep the ppid map until the
+      # subtree stops growing. Depth is unbounded, which is the point.
+      inset[root] = 1
+      changed = 1
+      while (changed) {
+        changed = 0
+        for (p in ppid) {
+          if (!(p in inset) && (ppid[p] in inset)) { inset[p] = 1; changed = 1 }
+        }
+      }
+      # THE ROOT ITSELF IS EXCLUDED. The recorded pid is the loop shell by
+      # construction, and a shell that matched would make every desk read alive.
+      for (p in inset) {
+        if (p == root) continue
+        if (index(comm[p], want) > 0) { exit 0 }
+      }
+      exit 1
+    }'
+}
+
 # Whether a RUNNING worker's child is doing work — `working`, `idle`, or "".
 #
 # A CUE, NOT A STATE. The row already reads `running`; this is the secondary
@@ -691,7 +825,54 @@ plot_worker_state() { # $1=worktree $2=pr-fact → "state\tpid\tcode"
         return
       fi
     fi
-    # The process is running AND current (or uncheckable, with no startedAt).
+    # THE WRAPPER LIVES. DOES AN AGENT? `kill -0` answered about the loop shell,
+    # and that shell outlives its agent for the whole `Worker bound` — measured
+    # 2026-09-11, four agents ended mid-slice and every one reported `running`.
+    # So the pid answering is a precondition for this question, never the answer
+    # to it.
+    #
+    # ONLY A DEFINITE ABSENCE MOVES THE READING. Return 2 is *could not look* —
+    # a pid that vanished between `kill -0` and here — and it falls through to
+    # `running`, which is what this reported before the reading existed. Absent
+    # is not false.
+    #
+    # AND THE QUESTION IS ONLY ASKED OF A DESK PLOT LAUNCHED A WORKER INTO,
+    # which `.plot-worker.wrapper.pid` is the proof of. A recorded pid with no
+    # wrapper file beside it was never started by `start_worker` — a hand-made
+    # desk, or a fixture writing a pid by hand — so Plot has no grounds to
+    # expect an agent beneath it, and asking would reinterpret every such pid as
+    # an orphan.
+    #
+    # Measured 2026-09-12 in CI: `--status` reported `finished` for a desk whose
+    # recorded pid was the TEST RUNNER — alive 1436 s, with no agent beneath it.
+    # The grace window cannot catch that, because the process is old.
+    #
+    # THE WRAPPER FILE RATHER THAN THE MANIFEST, and that is a measurement too:
+    # the one genuinely orphaned desk on this machine carries NO manifest — the
+    # registry it was written to has moved — and gating on one defeated the
+    # detection for exactly the population this exists to serve. The wrapper
+    # file is also the better evidence: the manifest is written by the
+    # dispatcher BEFORE the launch, while this file is written by the wrapper
+    # process itself, so its presence proves a worker really ran here. It is the
+    # file's own rule one line over — *"the process that knows a pid is the one
+    # that writes it"*.
+    if [ ! -f "$wt/.plot-worker.wrapper.pid" ]; then
+      printf 'running\t%s\t' "$pid"
+      return
+    fi
+    if plot_worker_agent_alive "$pid"; then
+      printf 'running\t%s\t' "$pid"
+      return
+    elif [ "$?" -eq 1 ]; then
+      # The wrapper is alive and the agent is gone. The DESK decides what that
+      # means — `stalled` for work only this machine holds, `waiting` for a
+      # marker, `finished` for a desk that is clear — because the process has
+      # nothing left to say. No exit file exists: the wrapper has not exited.
+      printf '%s\t%s\t' "$(plot_worker_task_state "$wt" "$has_pr")" "$pid"
+      return
+    fi
+    # Unaskable: the process table could not be read for this pid. Report what
+    # `kill -0` established and nothing more.
     printf 'running\t%s\t' "$pid"
     return
   fi
@@ -780,7 +961,9 @@ plot_worker_state() { # $1=worktree $2=pr-fact → "state\tpid\tcode"
 #
 #   worktree_here  pid_recorded  liveness  exit  blocked  dirty  unpushed
 #
-# `liveness` is `live`, `stale` or `dead`; `exit` is the code as read, empty for
+# `liveness` is `live`, `stale`, `orphaned` or `dead` — `orphaned` being a pid
+# that answers with no agent process under it, which is a live wrapper whose
+# agent has gone; `exit` is the code as read, empty for
 # an unreadable record and the literal `-` for an absent one, because an empty
 # field cannot say which of the two it is and the rule answers them alike only
 # because it was told they differ. The PR fact is NOT here: it comes from the
@@ -825,7 +1008,23 @@ plot_worker_readings() { # $1=worktree → "here\tpid\tliveness\texit\tblocked\t
       # uncheckable pid honest rather than pessimistic.
       if [ -n "$started_at" ] && ! plot_pid_is_current "$pid" "$started_at"; then
         liveness=stale
+      elif [ ! -f "$wt/.plot-worker.wrapper.pid" ]; then
+        # NO WRAPPER FILE, NO AGENT QUESTION — the gate `plot_worker_state`
+        # applies, repeated here because these two must not drift: a desk Plot
+        # never launched a worker into has no agent Plot can expect.
+        liveness=live
+      elif plot_worker_agent_alive "$pid"; then
+        liveness=live
+      elif [ "$?" -eq 1 ]; then
+        # THE FOURTH WORD, and it belongs in this field rather than in a private
+        # branch inside `plot_worker_state`. `stale` set the precedent: it means
+        # *the pid exists and is not our worker*, and this means *the pid exists
+        # and our worker is no longer inside it*. Both are facts about what the
+        # recorded pid names, which is what this field is.
+        liveness=orphaned
       else
+        # Unaskable — `kill -0` answered, the process table did not. Report what
+        # was established.
         liveness=live
       fi
     fi