Roadmap item 3: Add the inactive canonical state scanner

README.md

@@ -183,6 +183,24 @@ references. The package stays inactive, stores nothing, grants no authority, and
 performs no candidate, credential, network, adapter, publish, deploy, or external
 write.
 
+## Inactive canonical state scanner
+
+`orchestrator/v1/scan-state.sh` reads one bounded canonical snapshot that binds an
+explicit Git repository and commit and carries canonical stage request, resolved
+profile, attempt, and result records. Run it with the same repository and commit
+identities:
+
+```text
+orchestrator/v1/scan-state.sh scan REPOSITORY_ID COMMIT_ID SNAPSHOT.json
+```
+
+It emits a deterministic canonical observation that classifies each stage as
+terminal, stale, blocked, retryable, stranded, or pending, with a recovery action
+and reason. Those fields are messages for later recovery work, not commands. The
+scanner is inactive and observation only: it does not deliver events, schedule,
+dispatch, retry, reconcile, write state, use a credential or network, activate a
+profile, or touch a target.
+
 ## The current default team
 
 You talk **only** to yshifu, in a Claude Code session. yshifu orchestrates the other roles

RESTORE.md

@@ -422,6 +422,20 @@ launcher is not self-attested. It does not read proof bytes, establish proof
 truth, qualify a workflow, store evidence, grant authority, activate a profile,
 run a candidate or adapter, or perform a network or external-write action.
 
+Restore the five paths in the manifest's inactive canonical state scanner block
+from the same commit. With the same pinned, architecture-bound jq 1.6 runtime used
+by the portable core, run:
+
+```sh
+bash scripts/test/orchestrator-state-scanner.test.sh
+```
+
+This checks bounded canonical snapshots, exact repository and commit binding,
+deterministic pending and stranded classifications, recovery reasons, private
+runtime snapshots, and fail-closed input handling. The scanner remains inactive
+and observation only. It does not deliver or retry events, reconcile or write
+state, use a credential or network, activate a profile, or touch a target.
+
 ---
 
 ## 5. Smoke test — prove the rebuilt team is alive

ci/required-files.txt

@@ -217,3 +217,10 @@ scripts/test/control-evidence-integrity.test.sh
 # Inactive Control foundation policy roll-up
 control/v1/control-policy-set.json
 scripts/test/control-foundation-rollup.test.sh
+
+# Inactive canonical orchestrator state scanner
+orchestrator/v1/scan-state.sh
+orchestrator/v1/state-scanner-launcher.sh
+orchestrator/v1/state-scanner-driver.sh
+orchestrator/v1/state-scanner.jq
+scripts/test/orchestrator-state-scanner.test.sh

orchestrator/v1/scan-state.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+
+entrypoint=${BASH_SOURCE[0]}
+case "$entrypoint" in
+  /*) ;;
+  *) entrypoint="$PWD/$entrypoint" ;;
+esac
+launcher="${entrypoint%/*}/state-scanner-launcher.sh"
+requested_tmp=${TMPDIR:-/tmp}
+/usr/bin/env -i LC_ALL=C PATH=/usr/bin:/bin TMPDIR="$requested_tmp" \
+  /bin/bash "$launcher" "$@"

orchestrator/v1/state-scanner-driver.sh

@@ -0,0 +1,187 @@
+#!/bin/bash
+set -uo pipefail
+export LC_ALL=C
+umask 077
+
+emit_error() {
+  case "${1:-}" in
+    E_USAGE|E_RUNTIME|E_LIMIT|E_PARSE|E_CANONICAL|E_SHAPE|E_RELATION|E_STALE)
+      /usr/bin/printf '%s\n' "$1" >&2
+      ;;
+    *) /usr/bin/printf '%s\n' E_RUNTIME >&2 ;;
+  esac
+  exit 1
+}
+
+sha256_path() {
+  /usr/bin/shasum -a 256 "$1" | /usr/bin/awk '{print $1}'
+}
+
+sha256_line() {
+  builtin printf '%s\n' "$1" | /usr/bin/shasum -a 256 |
+    /usr/bin/awk '{print $1}'
+}
+
+verify_hash() {
+  [ -f "$2" ] && [ ! -L "$2" ] &&
+    [ "$(sha256_path "$2")" = "$1" ]
+}
+
+[ "$#" -eq 8 ] && [ "$1" = run ] || emit_error E_USAGE
+expected_repository_id=$2
+expected_commit_id=$3
+runtime=$4
+input=$5
+evaluator=$6
+evaluator_sha256=$7
+snapshot_sha256=$8
+
+self=${BASH_SOURCE[0]}
+case "$self" in /*) ;; *) emit_error E_RUNTIME ;; esac
+self_dir=$(CDPATH='' cd -P -- "${self%/*}" 2>/dev/null && pwd -P) ||
+  emit_error E_RUNTIME
+self="$self_dir/${self##*/}"
+[ "$self" = "$runtime/driver.sh" ] && [ "$self_dir" = "$runtime" ] ||
+  emit_error E_RUNTIME
+[ -d "$runtime" ] && [ ! -L "$runtime" ] || emit_error E_RUNTIME
+runtime_parent=${runtime%/*}
+case "$input" in "$runtime_parent"/input.json) ;; *) emit_error E_RUNTIME ;; esac
+case "$evaluator" in "$runtime"/evaluator.json) ;; *) emit_error E_RUNTIME ;; esac
+
+generation=g-392d20099dfa99872764009b268c8871914b4dbc0da467ec346baa921818ae3e
+modules="$runtime/core/v2/generations/$generation/modules"
+program="$runtime/program.jq"
+jq_bin="$runtime/jq"
+work="$runtime_parent/work"
+verify_runtime() {
+  verify_hash 8838c85aae5a2ed9ada659ae1a13c5cf8f561463789d1d5d9f28370d479f6c80 \
+    "$program" &&
+  verify_hash f55b697716dc13a6d2c71bde7769493b3f4b091fd7a94d3280c5d417974df3a1 \
+    "$runtime/core/v2/generation-registry.json" &&
+  verify_hash 65eb40b9afb9b4f1d809ed66d0f2ca625f656c34e856cedcde9cbbde857f0f0a \
+    "$runtime/core/v2/generations/$generation/contracts.jq" &&
+  verify_hash db87c6e97e93dc2a6eebd83087878c04f5528badc620d57fc9d883694e2ac28b \
+    "$runtime/core/v2/generations/$generation/core-ingress.sh" &&
+  verify_hash c00f9cfbe88df5cb1dbcfbead61288ff7d68684d43d095e74f26e7820f0d7207 \
+    "$modules/profile_graph.jq" &&
+  verify_hash 8e49c2c091f1bbe525f7499e3fca072f6916a14d5bb34adbf121439e8ca2d281 \
+    "$modules/result_facts.jq" &&
+  verify_hash ed992f26761d08e3c3f5ab57eda9bcd771ad59e3aebeb02643de88844184d2d3 \
+    "$modules/result_truth.jq" &&
+  verify_hash 8d1d02d36ac7ada778f05248f9413062b3fc251499914c15d79f003bbd009ade \
+    "$modules/schema.jq" &&
+  verify_hash 6572a6ecbac332dc9c4a8ef35acd1feebdc2e8aab04941fc0b756f3a5cbcf29e \
+    "$modules/stage_request.jq" &&
+  verify_hash bdb5def832e8e611bba8a7b30a2aae95ea4f2701c44b198cf51cd3dfd9ff88f3 \
+    "$runtime/scripts/core-contract.sh" &&
+  [ -f "$jq_bin" ] && [ -x "$jq_bin" ] && [ ! -L "$jq_bin" ] &&
+  { [ "$(sha256_path "$jq_bin")" = \
+        af986793a515d500ab2d35f8d2aecd656e764504b789b66d7e1a0b727a124c44 ] ||
+    [ "$(sha256_path "$jq_bin")" = \
+        5c0a0a3ea600f302ee458b30317425dd9632d1ad8882259fcaf4e9b868b2b1ef ]; }
+}
+
+verify_runtime || emit_error E_STALE
+[ -d "$work" ] && [ ! -L "$work" ] || emit_error E_RUNTIME
+[ -f "$input" ] && [ ! -L "$input" ] &&
+  [ "$(sha256_path "$input")" = "$snapshot_sha256" ] || emit_error E_RUNTIME
+[ -f "$evaluator" ] && [ ! -L "$evaluator" ] &&
+  [ "$(sha256_path "$evaluator")" = "$evaluator_sha256" ] || emit_error E_RUNTIME
+
+raw_size=$(/usr/bin/wc -c < "$input" | /usr/bin/tr -d ' ') || emit_error E_RUNTIME
+[ "$raw_size" -le 1048576 ] || emit_error E_LIMIT
+bom=$(/usr/bin/od -An -tx1 -N3 "$input" 2>/dev/null | /usr/bin/tr -d ' \n') ||
+  emit_error E_RUNTIME
+[ "$bom" != efbbbf ] || emit_error E_PARSE
+"$jq_bin" . "$input" >/dev/null 2>&1 || emit_error E_PARSE
+[ "$("$jq_bin" -s 'length' "$input" 2>/dev/null)" -eq 1 ] || emit_error E_PARSE
+"$jq_bin" -S -c . "$input" > "$work/input-canonical.json" 2>/dev/null ||
+  emit_error E_PARSE
+/usr/bin/cmp -s "$input" "$work/input-canonical.json" || emit_error E_CANONICAL
+"$jq_bin" -S -c . "$evaluator" > "$work/evaluator-canonical.json" 2>/dev/null ||
+  emit_error E_RUNTIME
+/usr/bin/cmp -s "$evaluator" "$work/evaluator-canonical.json" || emit_error E_RUNTIME
+
+"$jq_bin" -e '
+  def depth:
+    if type == "array" then (if length == 0 then 1 else 1 + ([.[]|depth]|max) end)
+    elif type == "object" then (if length == 0 then 1 else 1 + ([.[]|depth]|max) end)
+    else 1 end;
+  def members:
+    if type == "array" then length + ([.[]|members]|add // 0)
+    elif type == "object" then (keys_unsorted|length) + ([.[]|members]|add // 0)
+    else 0 end;
+  def strings_ok:
+    if type == "array" then all(.[];strings_ok)
+    elif type == "object" then
+      all(keys_unsorted[];utf8bytelength <= 8192) and all(.[];strings_ok)
+    elif type == "string" then utf8bytelength <= 8192 else true end;
+  depth <= 32 and members <= 16384 and strings_ok
+' "$input" >/dev/null 2>&1 || emit_error E_LIMIT
+
+item_count=$("$jq_bin" -r '
+  .body.items | if type == "array" then length else 0 end
+' "$input" 2>/dev/null) || emit_error E_RUNTIME
+: >"$work/item-sha-lines"
+i=0
+while [ "$i" -lt "$item_count" ]; do
+  content=$("$jq_bin" -S -c ".body.items[$i]" "$input") || emit_error E_RUNTIME
+  sha256_line "$content" >>"$work/item-sha-lines" || emit_error E_RUNTIME
+  i=$((i + 1))
+done
+"$jq_bin" -R -s -c 'split("\n")[:-1]' "$work/item-sha-lines" \
+  >"$work/item-shas.json" 2>/dev/null || emit_error E_RUNTIME
+
+result=$("$jq_bin" -L "$modules" -S -c -r \
+  --arg scanner_operation scan \
+  --arg expected_repository_id "$expected_repository_id" \
+  --arg expected_commit_id "$expected_commit_id" \
+  --arg snapshot_sha256 "$snapshot_sha256" \
+  --arg evaluator_sha256 "$evaluator_sha256" \
+  --slurpfile evaluator_docs "$evaluator" \
+  --slurpfile item_sha_docs "$work/item-shas.json" \
+  --slurpfile snapshot_docs /dev/null --slurpfile candidate_docs /dev/null \
+  -f "$program" "$input" 2>/dev/null) || emit_error E_RUNTIME
+case "$result" in E_SHAPE|E_RELATION|E_STALE) emit_error "$result" ;; esac
+
+/usr/bin/printf '%s\n' "$result" > "$work/candidate.json"
+"$jq_bin" -S -c . "$work/candidate.json" > "$work/candidate-canonical.json" \
+  2>/dev/null || emit_error E_RUNTIME
+/usr/bin/cmp -s "$work/candidate.json" "$work/candidate-canonical.json" ||
+  emit_error E_RUNTIME
+
+i=0
+while [ "$i" -lt "$item_count" ]; do
+  for pair_name in request resolved_profile; do
+    expected=$("$jq_bin" -r ".body.items[$i].$pair_name.sha256 // empty" "$input") ||
+      emit_error E_RUNTIME
+    content=$("$jq_bin" -S -c ".body.items[$i].$pair_name.content" "$input") ||
+      emit_error E_RUNTIME
+    [ -n "$expected" ] && [ "$(sha256_line "$content")" = "$expected" ] ||
+      emit_error E_RELATION
+  done
+  if [ "$("$jq_bin" -r ".body.items[$i].latest_result.state" "$input")" = present ]; then
+    expected=$("$jq_bin" -r ".body.items[$i].latest_result.value.sha256" "$input") ||
+      emit_error E_RUNTIME
+    content=$("$jq_bin" -S -c ".body.items[$i].latest_result.value.content" "$input") ||
+      emit_error E_RUNTIME
+    [ "$(sha256_line "$content")" = "$expected" ] || emit_error E_RELATION
+  fi
+  i=$((i + 1))
+done
+
+"$jq_bin" -n -e -L "$modules" \
+  --arg scanner_operation validate-observation \
+  --arg expected_repository_id "$expected_repository_id" \
+  --arg expected_commit_id "$expected_commit_id" \
+  --arg snapshot_sha256 "$snapshot_sha256" \
+  --arg evaluator_sha256 "$evaluator_sha256" \
+  --slurpfile evaluator_docs "$evaluator" \
+  --slurpfile item_sha_docs "$work/item-shas.json" \
+  --slurpfile snapshot_docs "$input" \
+  --slurpfile candidate_docs "$work/candidate.json" \
+  -f "$program" >/dev/null 2>&1 || emit_error E_RUNTIME
+verify_runtime || emit_error E_STALE
+[ "$(sha256_path "$input")" = "$snapshot_sha256" ] &&
+  [ "$(sha256_path "$evaluator")" = "$evaluator_sha256" ] || emit_error E_RUNTIME
+/bin/cat "$work/candidate.json"