B3-F1c-g VPS dot-dot-health Scheduler Repair — PATCH Artifact (live-targeted)

Mode: COMPILE PATCH ONLY (no execution, no file modification, no cron change, no PG mutation) Target: /opt/incomex/dot/bin/dot-dot-health on VPS (38.242.240.89) Live VPS version: v2.0.0 (Fix25, 2026-04-21) — generic executor dispatch Line count: 555 Supersedes: p3d-birth-b3f1c-g-dot-dot-health-scheduler-repair-patch.md (local-clone-based, v1.0.0) Companion rollback: p3d-birth-b3f1c-g-vps-dot-dot-health-scheduler-repair-rollback.md Companion report: p3d-birth-b3f1c-g-vps-scheduler-repair-patch-report.md Driver: GPT review gpt-review-b3-eld-design-and-b3f1c-g-patch-conditional-approval-2026-05-14.md — recompile against live VPS required before execution approval.

---

0. Live VPS divergence summary

The previous patch artifact was compiled against web-test/dot/bin/dot-dot-health v1.0.0 (301 lines, inline 9 hardcoded checks, no real parse_args). The live VPS file is completely different — v2.0.0 (Fix25, 2026-04-21), 555 lines, generic executor dispatch pattern reading checks from system_health_checks.

Both repair intents from the GPT-approved design pattern still apply, but the exact patch locations and surrounding context are different. This artifact recompiles against the live source.

---

1. Live VPS evidence (read-only)

1.1 Header (lines 1-25)

#!/usr/bin/env bash
# VERSION: 2.0.0
# CHANGELOG:
#   v2.0.0 (2026-04-21): Fix25 — generic executor dispatch.
#   v1.0.0 (2026-03-31): 9 hardcoded checks inline (RETIRED, see .bak-fix25).
# Usage:
#   dot-dot-health [--dry-run] [--only-check=<code>] [--verbose]

Note: VPS usage docs do not mention --local or --cloud. Env is loaded from /opt/incomex/secrets/.env.production (Đ33 §14 SSOT, line 79), so --local/--cloud are semantically irrelevant on this version — but cron still passes --local.

1.2 parse_args function (lines 164-180) — confirmed defect location

parse_args() {
  while [[ $# -gt 0 ]]; do
    case "$1" in
      --help|-h)             usage; exit 0 ;;
      --dry-run)             DRY_RUN=1; shift ;;
      --verbose)             VERBOSE=1; shift ;;
      --only-check=*)        ONLY_CHECK="${1#*=}"; shift ;;
      --only-check)
        [[ $# -lt 2 ]] && { log_err "--only-check requires value"; exit 2; }
        ONLY_CHECK="$2"; shift 2 ;;
      *)
        log_err "Unknown option: $1"
        usage >&2
        exit 2 ;;
    esac
  done
}

The strict default case *) log_err ... exit 2 actively rejects --local. local_flag_currently_accepted=false. Defect REPRODUCED on live source.

1.3 main "$@" tail (line 555) — confirmed source-time mutation risk

main() {                                # line 538
  parse_args "$@"

  log_info "${SCRIPT_NAME} v${VERSION}"
  log_info "only_check=${ONLY_CHECK:-<all>} dry_run=${DRY_RUN} verbose=${VERBOSE}"

  log_info "=== PRECHECK ==="
  precheck

  log_info "=== HEALTH CHECKS (generic executor §9) ==="
  if ! verify_all; then
    log_err "${SCRIPT_NAME} completed with critical failures"
    exit 1
  fi
  log_ok "${SCRIPT_NAME} completed"
  exit 0
}

main "$@"                               # line 555 (last line)

Bare main "$@" at line 555. bash_source_guard_present=false. Same B3-F1c-f source-time mutation risk applies (sourcing the file fires main "$@", which calls parse_args → precheck → verify_all → log_issue → fn_log_issue → system_issues INSERT).

1.4 Cron entry (root crontab, confirmed via crontab -l)

0 3 * * * . /opt/incomex/scripts/cron-env.sh && export DIRECTUS_ADMIN_EMAIL DIRECTUS_ADMIN_PASSWORD && /opt/incomex/dot/bin/dot-dot-health --local >> /var/log/incomex/dot-health.log 2>&1

Daily 03:00 UTC. Passes --local. Currently failing with exit 2 (Unknown option) before any check runs.

1.5 Mutation surfaces on live source (informational)

Path	Function	Target	DRY_RUN guarded?
log_issue (line 55-66) → fn_log_issue	PG function call	INSERT into system_issues	YES (lines 145, 156)
verify_all → run_pg_rw (line 68)	PG read	SELECT from system_health_checks	N/A (read)
precheck → env_load (line 78)	reads /opt/incomex/secrets/.env.production	filesystem read	N/A
precheck → run_pg_rw (lines 189, 196)	PG read	SELECT 1, normative_registry lookup	N/A (read)

Important: --dry-run is technically non-mutating to system_issues per the source guards, BUT it still triggers env_load + PG reads. Excluded from verification plan per hard boundary "No running dot-dot-health".

---

2. Repair Decision (carry-forward from approved pattern)

Selected: ADD_LOCAL_NOOP_FLAG (per GPT review §"B3-F1c-g patch review > Accepted as design pattern").

Plus: Add BASH_SOURCE safe source guard (per same review).

Both rationales unchanged from the previous artifact. Cron line not modified.

---

3. Patch Scope

Two surgical changes against live VPS source. Optionally, a third (documentation) change to keep usage text consistent.

#	Change	VPS lines	Required	Risk
H1	Add --local|--cloud) shift ;; no-op case inside parse_args	164-180	YES	None (no-op; shift mirrors sibling cases)
H2	Wrap main "$@" (line 555) in BASH_SOURCE[0] == "$0" guard	555	YES	None (preserves direct-exec, blocks source-time mutation)
H3 (optional)	Add --local|--cloud (no-op, legacy) line to usage() heredoc	144-162	OPTIONAL	None (stdout only)

Recommendation: apply H1+H2 only as the minimal repair. H3 is consistency-only and can be deferred to a doc-PR.

---

4. Unified Diff (against VPS live source)

--- a/opt/incomex/dot/bin/dot-dot-health
+++ b/opt/incomex/dot/bin/dot-dot-health
@@ -163,7 +163,7 @@ usage() {
 parse_args() {
   while [[ $# -gt 0 ]]; do
     case "$1" in
       --help|-h)             usage; exit 0 ;;
       --dry-run)             DRY_RUN=1; shift ;;
       --verbose)             VERBOSE=1; shift ;;
       --only-check=*)        ONLY_CHECK="${1#*=}"; shift ;;
       --only-check)
         [[ $# -lt 2 ]] && { log_err "--only-check requires value"; exit 2; }
         ONLY_CHECK="$2"; shift 2 ;;
+      --local|--cloud)       shift ;;  # no-op: legacy DOT scheduler convention (env loaded from SSOT, Đ33 §14)
       *)
         log_err "Unknown option: $1"
         usage >&2
         exit 2 ;;
     esac
   done
 }
@@ -552,4 +553,6 @@ main() {
   exit 0
 }
 
-main "$@"
+if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
+  main "$@"
+fi

---

5. Hunk Detail (annotated)

Hunk 1 — parse_args no-op (line 171 insertion)

Insertion point: after the --only-check) clause (line 173), before the strict default case (line 174).

Inserted line:

      --local|--cloud)       shift ;;  # no-op: legacy DOT scheduler convention (env loaded from SSOT, Đ33 §14)

Why shift: matches the convention of every sibling boolean flag (--dry-run, --verbose). Without shift, the loop infinite-loops.

Why --local|--cloud together: symmetry with the v1.0.0 documented usage [--cloud|--local]. If only --local were added, --cloud would silently exit 2 — leaving a partial gap. Both are no-ops at this version because env is loaded from /opt/incomex/secrets/.env.production (SSOT).

Why comment is one line, leads with "no-op": non-obvious why a documented flag is silently ignored. The comment explains why (SSOT env loading makes the flag semantically vestigial) without claiming it implements env selection.

Order rationale: placed before the *) default catch-all. Bash case matches first pattern, so order matters here.

Hunk 2 — safe source guard (line 555)

Before (line 555):

main "$@"

After:

if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
  main "$@"
fi

Rationale identical to prior artifact §4 Hunk 2: prevents the B3-F1c-f incident where source dot-dot-health triggers main → parse_args → precheck → verify_all → log_issue → system_issues INSERT. Direct-exec path (bash dot-dot-health … or /opt/incomex/dot/bin/dot-dot-health …) is byte-identical in behavior.

---

6. Verification Plan (NON-MUTATING ONLY)

All checks proven non-mutating against the live VPS source. No PG writes, no system_issues INSERT, no fn_log_issue call, no execution of main.

V1 — Syntax check

bash -n /opt/incomex/dot/bin/dot-dot-health
# Expected: exit 0, no output.

Proof: bash -n parses-only.

V2 — Static parse_args verification

sed -n '164,181p' /opt/incomex/dot/bin/dot-dot-health
# Expected: case block includes `--local|--cloud)  shift ;;` line, default `*)` case still present and unchanged.

grep -nE '^\s*--local\|--cloud\)' /opt/incomex/dot/bin/dot-dot-health
# Expected: exactly 1 match, inside parse_args range (lines 164-181).

Proof: sed -n and grep are read-only.

V3 — Static BASH_SOURCE guard verification

tail -5 /opt/incomex/dot/bin/dot-dot-health
# Expected last 4 lines:
#   }
#   if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
#     main "$@"
#   fi

grep -nE '^main "\$@"$' /opt/incomex/dot/bin/dot-dot-health
# Expected: 0 matches (bare invocation removed).

grep -nE 'BASH_SOURCE\[0\].*\$0' /opt/incomex/dot/bin/dot-dot-health
# Expected: 1 match (the guard).

Proof: tail, sed, grep are read-only.

V4 — --help invocation (PROVEN non-mutating on live source)

/opt/incomex/dot/bin/dot-dot-health --help
# Expected: prints usage banner; exits 0.

Proof of non-mutation on live source:

• main (line 538) calls parse_args "$@" first.
• parse_args matches --help|-h) → usage; exit 0 (line 167).
• Exit fires BEFORE precheck (line 195) → BEFORE env_load → BEFORE any run_pg_rw → BEFORE any log_issue / fn_log_issue / system_issues INSERT.
• usage() is cat <<USAGE … USAGE — stdout-only heredoc.
• No mutation surface is reachable on this path.

V5 — Combined --local --help invocation (PROVEN non-mutating)

/opt/incomex/dot/bin/dot-dot-health --local --help
# Expected: prints usage banner; exits 0.

Proof: With H1 applied, parse_args iterates: first iteration matches --local|--cloud) shift ;; (no exit, no side effect); second iteration matches --help|-h) usage; exit 0. This V5 specifically validates that (a) --local is accepted and (b) the rest of the parser still works. Same proof of non-mutation as V4.

V6 (EXCLUDED) — bare cron-like invocation

/opt/incomex/dot/bin/dot-dot-health --local           # EXCLUDED
/opt/incomex/dot/bin/dot-dot-health --local --dry-run # EXCLUDED

Excluded reasons:

• Bare --local: runs full verify_all, calls log_issue → INSERT to system_issues. MUTATING.
• --local --dry-run: provably skips log_issue (line 145, 156 guards), but still runs env_load + PG reads + DOT-H4/DOT-H7 builtins (which ls /opt/incomex/dot/bin and grep registry). Per hard boundary "No running dot-dot-health", excluded regardless of write status.

---

7. Apply Procedure (for reviewer, NOT executed by drafter)

# On VPS, after GPT approval. Run as root.
SRC=/opt/incomex/dot/bin/dot-dot-health
TS=$(date -u +%Y%m%dT%H%M%SZ)

# 1. Backup live script (timestamped):
cp -p "$SRC" "${SRC}.bak.b3f1c-g.${TS}"
sha256sum "$SRC" "${SRC}.bak.b3f1c-g.${TS}"  # hashes should match before patch

# 2. Apply patch (the two hunks above) — preferred: `patch -p1` from saved unified diff.
# 3. Run verification V1, V2, V3, V4, V5 in order; each must pass before proceeding.
# 4. Per memory feedback_git_commit_after_vps_edit.md:
cd /opt/incomex/dot && git add bin/dot-dot-health && git commit -m "fix(dot-dot-health): accept --local/--cloud no-op + safe source guard (B3-F1c-g)"
# 5. Wait for next cron tick at 03:00 UTC to validate end-to-end, OR (only if explicitly re-authorized) trigger once manually.

---

8. Caveats / Open Items

1. Cron line unchanged. --local survives as a vestigial flag. If a future refactor wants to drop the flag entirely, follow up by editing both the cron entry AND the no-op case in one synchronized PR.
2. --cloud is also accepted even though no current cron uses it. This is intentional symmetry with the legacy [--cloud|--local] usage convention and costs nothing.
3. H3 (usage doc update) deferred. The script's usage() heredoc still won't mention --local/--cloud after H1+H2 only. Acceptable because they're explicitly no-op compatibility flags — not features. Document in doc-PR if desired.
4. VPS commit follow-up required per memory feedback_git_commit_after_vps_edit.md — cd /opt/incomex/dot && git add -A && git commit after applying the patch on the host.
5. No system_issues write check after apply. Per hard boundaries, we cannot run the script bare. End-to-end validation must wait for the natural 03:00 UTC cron tick, monitored via tail -f /var/log/incomex/dot-health.log (read-only).

---

9. Status

b3f1c_g_vps_patch_compile_status=PASS
vps_file_read=true
vps_differs_from_local_artifact=true
local_flag_currently_accepted=false
local_flag_patch_needed=true
bash_source_guard_present=false
bash_source_guard_patch_needed=true
patch_compiled=true
verification_plan_non_mutating=true
execution_allowed=false
next_recommended_action=GPT_REVIEW_B3F1C_G_VPS_PATCH_ARTIFACT