@jenga-ai/agent 1.1.0 → 1.2.0

package/hooks/on_session_end.sh

@@ -7,8 +7,10 @@
 #   2. Detect new problem rapports using a manifest (not a timestamp)
 #      and write trigger payloads to the scrum master queue
 #   3. Write a status-review trigger to the scrum master queue
-#   4. Read .session_handoff.json (if present) and route the assignment
-#      to the correct next agent queue, then delete the handoff file
+#   4. Process every pending file under project/queue/handoffs/ (if any),
+#      routing each one's assignment to the correct next agent queue, then
+#      deleting that individual file immediately after it is routed — so a
+#      problem with one file never blocks or loses any of the others
 #
 # Pipeline routing (section 4):
 #   scrum-master  planning_complete       → developer_triggers.jsonl
@@ -26,18 +28,27 @@ source "$(git rev-parse --show-toplevel)/lib/resolve-project-dir.sh"
 
 PROJECT_DIR="$JENGA_PROJECT_DIR"
 RAPPORT_DIR="$PROJECT_DIR/project/rapports/problems"
-MANIFEST="$PROJECT_DIR/.claude/hooks/.rapport_manifest.json"
+# NOTE: this manifest lives under project/ (not .claude/) because .claude/
+# and .agents/ are generated build outputs, clobbered on every /distribute
+# or /self-sync run — see CLAUDE.md. Canonical, committed state must not
+# live inside a distribution target. Seed generated via, and kept in sync
+# by, scripts/generate-rapport-manifest.sh (see section 2 below).
+MANIFEST="$PROJECT_DIR/project/data/rapport_manifest.json"
 QUEUE_DIR="$PROJECT_DIR/project/queue"
 QUEUE_FILE="$QUEUE_DIR/scrum_triggers.jsonl"
 DEV_QUEUE="$QUEUE_DIR/developer_triggers.jsonl"
 TESTER_QUEUE="$QUEUE_DIR/tester_triggers.jsonl"
-HANDOFF_FILE="$QUEUE_DIR/.session_handoff.json"
+# Per-session handoff files (E37_S01_T01) replace the old single-slot
+# .session_handoff.json. Every file under this directory is processed in
+# section 4 below; see templates/SCRUM_BOARD_SCHEMA.md's handoffs/ section
+# for the write-side filename convention.
+HANDOFF_DIR="$QUEUE_DIR/handoffs"
 EVENTS_LOG="$PROJECT_DIR/project/logs/events.json"
 AGENT="${JENGA_AGENT_TYPE:-unknown}"
 SESSION_ID="${JENGA_SESSION_ID:-}"
 TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 
-mkdir -p "$PROJECT_DIR/project/logs" "$QUEUE_DIR"
+mkdir -p "$PROJECT_DIR/project/logs" "$QUEUE_DIR" "$HANDOFF_DIR"
 
 # --- 1. Log sender object ---
 
@@ -58,18 +69,55 @@ SENDER=$(jq -n \
     }
   }')
 
-if [ -f "$EVENTS_LOG" ]; then
-  jq --argjson entry "$SENDER" '. += [$entry]' "$EVENTS_LOG" > /tmp/events_tmp.json \
-    && mv /tmp/events_tmp.json "$EVENTS_LOG"
+# The read-modify-write below is wrapped in scripts/with-lock.sh (E37_S01_T03)
+# so concurrent on_session_end.sh invocations never interleave their read and
+# write of $EVENTS_LOG — see E37_S01_T04 and the two rapports it links
+# (project/rapports/problems/E37_S01-concurrent-session-end-race-verification-gap.md,
+# project/rapports/problems/E39_S03_T05-events-json-concurrent-write-corruption.md)
+# for the concurrent-invocation data loss (events.json truncated to 0 bytes)
+# this replaces. The temp file used for the atomic `mv` is created via
+# `mktemp` in the SAME directory as $EVENTS_LOG (not a shared
+# /tmp/events_tmp.json path) so it is (a) unique per invocation — no two
+# concurrent processes can ever collide on the same temp filename — and
+# (b) on the same filesystem as the destination, so the final `mv` stays an
+# atomic rename rather than a cross-filesystem copy. The update logic is
+# captured as a standalone script string (via a quoted heredoc, so jq's own
+# `$entry` and quoting pass through untouched by this outer shell) and run
+# through `bash -c` with $EVENTS_LOG/$SENDER passed as positional args
+# rather than interpolated into the script text, avoiding fragile
+# nested-quote escaping while keeping this fix self-contained in this file.
+APPEND_EVENT_SCRIPT=$(cat <<'EOS'
+events_log="$1"
+sender_json="$2"
+tmp_file=$(mktemp "$(dirname "$events_log")/events_tmp.XXXXXX") || exit 1
+if [ -s "$events_log" ]; then
+  jq --argjson entry "$sender_json" '. += [$entry]' "$events_log" > "$tmp_file" \
+    && mv "$tmp_file" "$events_log"
 else
-  echo "[$SENDER]" > "$EVENTS_LOG"
+  printf '[%s]' "$sender_json" > "$tmp_file" \
+    && mv "$tmp_file" "$events_log"
 fi
+rc=$?
+[ -f "$tmp_file" ] && rm -f "$tmp_file"
+exit "$rc"
+EOS
+)
+
+"$PROJECT_DIR/scripts/with-lock.sh" "$EVENTS_LOG" -- bash -c "$APPEND_EVENT_SCRIPT" _ "$EVENTS_LOG" "$SENDER"
 
 # --- 2. Manifest-based rapport detection ---
 # Use a JSON array of known filenames instead of a mtime sentinel file.
 # This prevents silently missing rapports written before the session ends
 # but after the sentinel was last touched.
+#
+# The manifest itself is committed to the repo (seeded and kept in sync via
+# scripts/generate-rapport-manifest.sh), so on a normal checkout it already
+# exists and reflects the rapports present at commit time. The bootstrap
+# below is a non-destructive fallback for the genuinely unexpected case
+# where the file is missing (e.g. project/data/ was pruned) — it does not
+# run on a fresh clone with the manifest intact.
 
+mkdir -p "$(dirname "$MANIFEST")"
 if [ ! -f "$MANIFEST" ]; then
   echo "[]" > "$MANIFEST"
 fi
@@ -77,12 +125,28 @@ fi
 if [ -d "$RAPPORT_DIR" ]; then
   # Collect current rapport files (exclude .IGNORE.md files — already resolved)
   # Results are stored in a bash array to avoid word-splitting on paths.
-  mapfile -t CURRENT_FILES < <(find "$RAPPORT_DIR" -name "*.md" ! -name "*.IGNORE.md" 2>/dev/null | sort)
+  # Uses a portable `while read` loop rather than mapfile/readarray: macOS
+  # ships bash 3.2 (no mapfile support), and this hook must run there —
+  # matches the convention already established in scripts/smoke-harness.sh,
+  # skills/publish/scripts/generate_release_notes.sh, and
+  # skills/publish/scripts/finalize_changelog.sh. Fixed incidentally here
+  # because this task's acceptance criteria require the hook to actually
+  # execute end-to-end (mapfile silently failed on stock macOS bash,
+  # leaving CURRENT_FILES empty and masking real detection results).
+  CURRENT_FILES=()
+  while IFS= read -r line; do
+    [ -n "$line" ] && CURRENT_FILES+=("$line")
+  done < <(find "$RAPPORT_DIR" -name "*.md" ! -name "*.IGNORE.md" 2>/dev/null | sort)
 
-  # Identify new files not present in the manifest
+  # Identify new files not present in the manifest. The manifest stores
+  # paths relative to $PROJECT_DIR (portable across clones/worktrees), so
+  # each absolute CURRENT_FILES entry is relativized before the lookup.
+  # NEW_FILES itself stays absolute — it feeds rapport_files in the
+  # trigger below, which the scrum master reads directly.
   NEW_FILES=()
   for file in "${CURRENT_FILES[@]}"; do
-    known=$(jq --arg f "$file" 'index($f) != null' "$MANIFEST" 2>/dev/null)
+    rel="${file#"$PROJECT_DIR"/}"
+    known=$(jq --arg f "$rel" 'index($f) != null' "$MANIFEST" 2>/dev/null)
     if [ "$known" != "true" ]; then
       NEW_FILES+=("$file")
     fi
@@ -109,8 +173,11 @@ if [ -d "$RAPPORT_DIR" ]; then
 
     echo "$TRIGGER" >> "$QUEUE_FILE"
 
-    # Update the manifest to include all current files
-    printf '%s\n' "${CURRENT_FILES[@]}" | jq -R . | jq -s . > "$MANIFEST"
+    # Update the manifest to include all current files. Delegates to the
+    # shared generator script (rather than re-inlining the same jq
+    # pipeline) so the runtime update and the committed seed can never
+    # drift in how they compute "current rapport files".
+    bash "$PROJECT_DIR/scripts/generate-rapport-manifest.sh" "$MANIFEST" >/dev/null
   fi
 fi
 
@@ -129,15 +196,97 @@ TRIGGER=$(jq -n \
 
 echo "$TRIGGER" >> "$QUEUE_FILE"
 
+# --- Helper: has this handoff's referenced task already reached a
+# terminal board status? ---------------------------------------------------
+# Guards against resurrecting a stale handoff file (e.g. one that was
+# accidentally committed to git alongside unrelated work, or one left over
+# from before this directory was ever consumed) as a fresh routing signal
+# for work that has already been fully verified. Terminal here means "no
+# further routing action should occur": Passed / Passed with remarks /
+# Rejected / Done are all end states, and Blocked is included because a
+# blocked task must not be silently re-touched by any agent per
+# agents/developer.md's Blocked-halt contract (only a human may clear it).
+# Deliberately fails open (returns 1 / "not terminal") when the task file
+# can't be found or has no readable status, so a lookup miss falls back to
+# today's behavior (route it) rather than silently dropping a handoff whose
+# task genuinely can't be identified.
+is_task_terminal() {
+  local task_id="$1" task_file task_status
+  task_file=$(find "$PROJECT_DIR/project/board/tasks" -maxdepth 1 -iname "${task_id}_*.md" 2>/dev/null | head -1)
+  [ -z "$task_file" ] && return 1
+  task_status=$(awk -F': ' '/^status:/ {print $2; exit}' "$task_file" 2>/dev/null)
+  case "$task_status" in
+    Passed|"Passed with remarks"|Rejected|Done|Blocked) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
 # --- 4. Session handoff routing ---
-# Each agent writes .session_handoff.json before its session ends.
-# This section reads that file and routes the work to the correct next
-# agent queue so the pipeline continues automatically.
+# Each agent writes a per-session handoff file under project/queue/handoffs/
+# before its session ends (see E37_S01_T01). This section processes every
+# file currently present in that directory — not just one fixed path — so
+# concurrent sessions ending close together each get routed instead of the
+# last writer silently clobbering the others. Every file is routed through
+# the same per-agent logic below, then deleted individually right after
+# routing, so a problem with one file can't block or lose any of the rest.
+#
+# The glob is intentionally generic (*.json, not a pattern anchored to the
+# <agent>-<session_id>-<task_id> convention) so it also picks up older
+# ad-hoc-named files written before that convention existed — routing below
+# only ever reads the .agent/.status fields from file contents, never the
+# filename, so this is safe.
+#
+# Before routing, a developer/tester handoff whose referenced task is
+# already terminal on the board is treated as stale (deleted, not routed)
+# rather than as a live signal — see is_task_terminal() above. This closes
+# a real regression found during E37_S01_T02 testing: this directory can
+# accumulate committed leftover files for already-shipped work (nothing
+# consumed them before this task existed), and a bare generic glob would
+# otherwise resurrect all of them as fresh test_assignment/story_rollup
+# triggers the moment this hook first runs against such a directory.
+for HANDOFF_FILE in "$HANDOFF_DIR"/*.json; do
+  # Guard against the glob matching nothing (no nullglob dependency, so
+  # this stays portable to stock macOS bash 3.2 — same rationale as the
+  # portable `while read` loop in section 2 above).
+  [ -e "$HANDOFF_FILE" ] || continue
+
+  # Atomic per-file claim (E37_S01_T04) — closes the TOCTOU window between
+  # this per-process glob snapshot and the eventual delete at the bottom of
+  # the loop. `mv` between two paths on the same filesystem is a rename(2)
+  # syscall: the kernel guarantees that when multiple concurrent processes
+  # race to rename the same source path, exactly one succeeds and every
+  # other attempt fails because the source no longer exists. No GNU-only
+  # flags are involved, so this is portable to macOS/BSD as well as Linux.
+  # Without this claim, concurrent invocations could each see the same
+  # not-yet-deleted file, read it, and route it before either deleted it —
+  # confirmed in project/rapports/problems/E37_S01-concurrent-session-end-race-verification-gap.md
+  # as duplicate (2x/2x/4x observed) trigger entries for the same handoff.
+  # If the rename fails, another concurrent process already claimed this
+  # exact file — skip it without reading, routing, or deleting anything;
+  # that other process now owns it.
+  CLAIMED_HANDOFF_FILE="${HANDOFF_FILE}.claimed.$$"
+  if ! mv "$HANDOFF_FILE" "$CLAIMED_HANDOFF_FILE" 2>/dev/null; then
+    echo "[on_session_end] handoff already claimed by a concurrent invocation — skipping $(basename "$HANDOFF_FILE")"
+    continue
+  fi
+  HANDOFF_FILE="$CLAIMED_HANDOFF_FILE"
 
-if [ -f "$HANDOFF_FILE" ]; then
   HANDOFF_AGENT=$(jq -r '.agent // empty' "$HANDOFF_FILE" 2>/dev/null)
   HANDOFF_STATUS=$(jq -r '.status // empty' "$HANDOFF_FILE" 2>/dev/null)
 
+  # Staleness check — only meaningful for developer/tester handoffs, which
+  # each reference exactly one task_id. scrum-master's planning_complete
+  # handoff carries a task_ids array of just-created tasks that can't
+  # already be terminal in practice, so it is not checked here.
+  if [ "$HANDOFF_AGENT" = "developer" ] || [ "$HANDOFF_AGENT" = "tester" ]; then
+    CHECK_TASK_ID=$(jq -r '.task_id // empty' "$HANDOFF_FILE" 2>/dev/null)
+    if [ -n "$CHECK_TASK_ID" ] && is_task_terminal "$CHECK_TASK_ID"; then
+      echo "[on_session_end] stale handoff for already-terminal task $CHECK_TASK_ID — skipping routing, deleting $(basename "$HANDOFF_FILE")"
+      rm -f "$HANDOFF_FILE"
+      continue
+    fi
+  fi
+
   case "$HANDOFF_AGENT" in
 
     scrum-master)
@@ -228,9 +377,11 @@ if [ -f "$HANDOFF_FILE" ]; then
 
   esac
 
-  # Consume the handoff file — it is single-use
+  # Consume this handoff file — it is single-use. Deleted immediately after
+  # routing (not batched after the loop) so a later file's failure can never
+  # cause an earlier, already-routed file to be left unconsumed or vice versa.
   rm -f "$HANDOFF_FILE"
-fi
+done
 
 # --- 5. Todo cleanup ---
 # Remove project/todo.md if it is effectively empty (only blanks, # Todo, and HTML comments).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jenga-ai/agent",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "JengaAgent — agentic project management CLI",
   "type": "module",
   "publishConfig": {

package/scripts/check-permission-level.sh

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+#
+# check-permission-level.sh — read-only gate for a skill's declared minimum
+# permission level (the `minimum_permission_level` SKILL.md frontmatter field,
+# see docs/skill-authoring.md).
+#
+# ============================================================================
+# CHECK vs ENFORCE — READ THIS BEFORE WIRING THIS SCRIPT INTO A SKILL
+# ============================================================================
+# This script is READ-ONLY. It CHECKS the current session's permission level
+# against a required minimum and SIGNALS the result. It does NOT:
+#   - prompt the user for confirmation
+#   - elevate the session level
+#   - write to .jenga-permission-level.json, .claude/settings.json, or
+#     .agents/settings.json under any code path
+#
+# The CALLING SKILL's own instructions are responsible for:
+#   1. Detecting the `NEEDS_CONFIRMATION` signal (non-zero exit) below.
+#   2. Explicitly asking the user to confirm elevation (no silent
+#      auto-elevation, ever).
+#   3. On confirmation, invoking `jenga-permission-level-switch.sh <minimum-level>`
+#      (a sibling script, scripts/jenga-permission-level-switch.sh — task E33_S02_T02) to
+#      actually perform the elevation.
+#   4. Immediately after the skill's own work completes, resetting the
+#      session back to Guarded (2) — typically via `jenga-permission-level-switch.sh 2` as
+#      the skill's last step. This reset is NOT automatic and is NOT this
+#      script's job.
+#
+# Usage:
+#   scripts/check-permission-level.sh <minimum-level>
+#
+#   <minimum-level>  Integer 1-5 — the value a calling skill read from its
+#                     own `minimum_permission_level` frontmatter field.
+#
+# Exit codes:
+#   0  Current session level already meets <minimum-level>. No output.
+#   1  Current session level is below <minimum-level>. Prints:
+#        NEEDS_CONFIRMATION: elevate from <current> to <minimum-level>
+#   2  Bad usage / invalid argument. Prints an error to stderr.
+#
+# Current level source:
+#   .jenga-permission-level.json at the repo root, field `session_level`
+#   (the format `jenga-permission-level-switch.sh`, E33_S02_T02, writes: {"session_level": <n>}).
+#   Missing file, unreadable file, malformed JSON, or a missing/non-integer
+#   `session_level` field are all treated as level 2 (Guarded), the
+#   permanent default — this script never fails merely because the level
+#   file is absent or malformed.
+# ============================================================================
+
+set -euo pipefail
+
+usage() {
+  echo "Usage: $(basename "$0") <minimum-level>" >&2
+  echo "  <minimum-level> must be an integer 1-5 (the skill's minimum_permission_level)." >&2
+}
+
+if [ "$#" -ne 1 ]; then
+  usage
+  exit 2
+fi
+
+MIN_LEVEL="$1"
+
+case "$MIN_LEVEL" in
+  1|2|3|4|5) ;;
+  *)
+    echo "Error: <minimum-level> must be an integer 1-5, got: '$MIN_LEVEL'" >&2
+    usage
+    exit 2
+    ;;
+esac
+
+LEVEL_FILE=".jenga-permission-level.json"
+CURRENT_LEVEL=2
+
+if [ -f "$LEVEL_FILE" ]; then
+  if command -v python3 >/dev/null 2>&1; then
+    PARSED=$(python3 -c "
+import json, sys
+try:
+    with open('$LEVEL_FILE') as f:
+        data = json.load(f)
+    level = data.get('session_level')
+    if isinstance(level, bool) or not isinstance(level, int) or not (1 <= level <= 5):
+        raise ValueError('invalid session_level')
+    print(level)
+except Exception:
+    print(2)
+" 2>/dev/null || echo 2)
+    CURRENT_LEVEL="$PARSED"
+  else
+    # No python3 available — fall back to a permissive grep-based extraction.
+    # Any failure to confidently parse an integer 1-5 falls back to level 2.
+    GREPPED=$(grep -o '"session_level"[[:space:]]*:[[:space:]]*[0-9]' "$LEVEL_FILE" 2>/dev/null | grep -o '[0-9]$' | head -n1 || true)
+    case "$GREPPED" in
+      1|2|3|4|5) CURRENT_LEVEL="$GREPPED" ;;
+      *) CURRENT_LEVEL=2 ;;
+    esac
+  fi
+fi
+
+if [ "$CURRENT_LEVEL" -ge "$MIN_LEVEL" ]; then
+  exit 0
+fi
+
+echo "NEEDS_CONFIRMATION: elevate from $CURRENT_LEVEL to $MIN_LEVEL"
+exit 1

package/scripts/check-publicignore-match.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+# ---------------------------------------------------------------------------
+# scripts/check-publicignore-match.sh
+#
+# Classify one or more repo-relative paths as PUBLIC (would ship to the
+# public mirror repo) or BLOCKED (excluded by .publicignore), using the
+# exact same rsync --exclude-from=.publicignore matching semantics as
+# skills/mirror-public/scripts/mirror.sh's --dry-run "ship list" computation
+# (see the SHIP_LIST_FILE block in that script). A file classified as
+# "would be blocked" by `/mirror-public --dry-run` is guaranteed to be
+# classified as BLOCKED here too, and vice versa for PUBLIC.
+#
+# This does NOT touch the network, clone the public repo, or require
+# /mirror-public to be configured (skills/mirror-public/assets/config.json
+# is never read) — it only needs a .publicignore file at the repo root.
+# Rsync's include/exclude filter evaluation does not depend on destination
+# state (destination state only affects delete/itemize-flag details for
+# files already present there), so probing against an empty scratch temp
+# directory yields an identical "would ship" set to probing against
+# mirror.sh's real public-clone destination.
+#
+# Callers (e.g. /doc-sync step 4, and the E36 changelog generator's
+# .publicignore-awareness) are expected to skip invoking this script
+# entirely when .publicignore does not exist at the repo root — that is
+# the established no-op-when-absent precedent, and it stays owned by each
+# caller rather than being silently absorbed here.
+#
+# Usage:
+#   check-publicignore-match.sh <path> [<path> ...]
+#
+# Paths are interpreted relative to the repo root (same convention as
+# `git ls-files`). Output: one "STATUS<TAB>path" line per input path, in
+# input order. STATUS is PUBLIC or BLOCKED.
+#
+# Note: a path that does not exist on disk is classified BLOCKED (it will
+# not appear in rsync's transfer list regardless of .publicignore). Callers
+# such as /doc-sync only ever pass paths already confirmed to exist as
+# real new-in-source candidates, so this does not arise in practice — but
+# it is not the same guarantee as ".publicignore explicitly matched it".
+#
+# Exit codes:
+#   0  classification completed (regardless of individual PUBLIC/BLOCKED results)
+#   1  usage error
+#   2  repo root not found, .publicignore missing, or rsync unavailable
+# ---------------------------------------------------------------------------
+
+set -euo pipefail
+IFS=$'\n\t'
+
+die() {
+  printf 'check-publicignore-match.sh: error: %s\n' "$*" >&2
+  exit 2
+}
+
+if [ "$#" -eq 0 ]; then
+  printf 'usage: check-publicignore-match.sh <path> [<path> ...]\n' >&2
+  exit 1
+fi
+
+SCRIPT_PATH="${BASH_SOURCE[0]}"
+while [ -h "$SCRIPT_PATH" ]; do
+  LINK_TARGET="$(readlink "$SCRIPT_PATH")"
+  case "$LINK_TARGET" in
+    /*) SCRIPT_PATH="$LINK_TARGET" ;;
+    *)  SCRIPT_PATH="$(cd "$(dirname "$SCRIPT_PATH")" && pwd)/$LINK_TARGET" ;;
+  esac
+done
+SCRIPT_DIR="$(cd "$(dirname "$SCRIPT_PATH")" && pwd)"
+
+REPO_ROOT="$(git -C "$SCRIPT_DIR" rev-parse --show-toplevel 2>/dev/null || true)"
+[ -n "$REPO_ROOT" ] || die "could not locate repo root (git rev-parse failed from $SCRIPT_DIR)"
+
+PUBLICIGNORE="$REPO_ROOT/.publicignore"
+[ -f "$PUBLICIGNORE" ] || die "no .publicignore at $PUBLICIGNORE (caller should skip invoking this script when absent — that is the no-op case, not an error the caller should surface)"
+
+command -v rsync >/dev/null 2>&1 || die "rsync not installed"
+
+TMP_DEST="$(mktemp -d)"
+SHIP_LIST_FILE="$(mktemp)"
+cleanup() {
+  rm -rf "$TMP_DEST"
+  rm -f "$SHIP_LIST_FILE"
+}
+trap cleanup EXIT
+
+# Same rsync flags + itemize/awk filter as mirror.sh's --dry-run ship-list
+# computation (kept in lockstep with that block intentionally), targeted at
+# an empty scratch dir instead of a real public clone.
+rsync -a --delete \
+  --exclude-from="$PUBLICIGNORE" \
+  --exclude=".git" \
+  --dry-run --itemize-changes --out-format='%i %n' \
+  "$REPO_ROOT/" \
+  "$TMP_DEST/" \
+  | awk '{
+      flag = $1;
+      first  = substr(flag, 1, 1);
+      second = substr(flag, 2, 1);
+      # Skip directories — public tree recreates them implicitly.
+      if (second == "d") next;
+      # Keep only entries that transfer or create a file/symlink/hardlink.
+      keep = 0;
+      if (first == ">" || first == "<") keep = 1;   # file transfer
+      else if (first == "c" && second == "L") keep = 1;  # create symlink
+      else if (first == "h") keep = 1;              # hard link
+      if (!keep) next;
+      $1 = "";
+      sub(/^ /, "");
+      sub(/\/$/, "");
+      if (length($0) > 0) print $0;
+    }' \
+  | LC_ALL=C sort -u > "$SHIP_LIST_FILE"
+
+for candidate in "$@"; do
+  # Normalize a single leading "./" if present, so callers can pass either form.
+  norm="${candidate#./}"
+  if LC_ALL=C grep -Fxq "$norm" "$SHIP_LIST_FILE"; then
+    printf 'PUBLIC\t%s\n' "$candidate"
+  else
+    printf 'BLOCKED\t%s\n' "$candidate"
+  fi
+done