amsd-pipeline-shared 0.5.0 → 0.5.2

package/docs/gateway-baseline-2.0.80.md5

@@ -41,3 +41,50 @@ bc5acdb9260923082e05ef3b67304028  scripts/preflight-static.sh
 f206025f304e8320b8417a6dd6606044  scripts/spec-mode-runner.js
 dfa070b168a7c01fab8aab5a46d16192  scripts/team-lead-review.sh
 40c65de8360d5a9f59902fca26d1d7a8  scripts/update-monitor.sh
+7ab104b57abcbc8cb3cd890c753d5d67  config/resume-preserves.json
+be822cc2faec79be223cf2cc1766ec4b  scripts/lib/checkpoints.sh
+448c8118bdab3697022e2f68f3a99801  scripts/lib/codeline-lanes.sh
+8ef595221a8fb9d4a60f531d302c33bd  scripts/lib/codeline-write-perimeter.sh
+a945f1483df090d9b053e1ea883fdb4c  scripts/lib/common.sh
+1fae91a1cd6b7304f23ba87ba88a7019  scripts/lib/control-plane.sh
+800e750c30be013c620ac76f28d41c20  scripts/lib/flags.sh
+3fd6c829074f18a67bf08b9d05a0256d  scripts/lib/git-ops.sh
+bbcb3501aa61f196ccb170a6166fde65  scripts/lib/halt-recovery.sh
+175d82c1706b45866ac6b1d0e6ddb9f5  scripts/lib/orchestration-resume.sh
+779412cd9db1a61deb307a9bcf6804f3  scripts/lib/phase-exit.sh
+a38009bef2909c164a449b2192bf4c75  scripts/lib/qa-gate-evidence.sh
+f64fdd6bc6df7e13d742e9e53a470be4  scripts/lib/release-lines.sh
+9768775dcd035b39932f3ebce243857e  scripts/lib/resume-semantics.sh
+9216939efdf63c244d42d91ba6fb466c  scripts/lib/run-checkpoint.sh
+886860d643c5db8fb3bfcf5bd3efaf9d  scripts/lib/run-modes.sh
+156cf302dcedf423dea01ccb11fe305d  scripts/lib/story-outputs.sh
+8e4481cc43b5efe2d7c032e8d2eb2f66  scripts/lib/story-retry-state.sh
+f2cf5c1489ba9cd3fde4522b8c249b8b  scripts/lib/handlers/_read-input.js
+38b31e37abb0fb6b9021673d22bd4d59  scripts/lib/handlers/carry-plan.js
+5d0397d7da5537c75fc0bc8b2bd7e9b9  scripts/lib/handlers/cl-entries.js
+35339f54cb483bbb79ff18100366b1d1  scripts/lib/handlers/codeline-ecosystem.js
+a2e6097447d4b4a2ee7bdcd5df42267a  scripts/lib/handlers/codeline-manifests.js
+a8ce1f16d6a7acc79cabbe1e8aa2523c  scripts/lib/handlers/filtered-prd.js
+b15485e34a3db5e860609b9685b36211  scripts/lib/handlers/merge-lane-into-canonical.js
+3d40afd95026d86ca6ff3cc4f6d11a10  scripts/lib/handlers/package-engines-node.js
+41d04505e7688043f0bdfc2ef41537b2  scripts/lib/handlers/prd-phases.js
+3d17d52aa9d40a73240108e66f022cca  scripts/lib/handlers/rebuild-cross-contract.js
+7dd7fadbb2e98fee9646cc3206a55744  scripts/lib/handlers/record-declared-pass.js
+fa0fb7977606fdb98777288e613b2666  scripts/lib/handlers/release-line-prd.js
+3cc434c139dbba56aed51c7485a53d27  scripts/lib/handlers/release-lines.js
+4e2a0f8465afb1d58664e3474d1e99f3  scripts/lib/handlers/repo-exclude-patterns.js
+fd4a27b6fb02b2d5dcb3e610ae126ec3  scripts/lib/handlers/resume-spec-output-present.js
+b3015f602e1cb07887b7c94954a0886e  scripts/lib/handlers/sibling-providers.js
+2a53c1cc2abab67f4a35504f8b70c2b9  scripts/lib/handlers/spanning-stories-incomplete.js
+8f796a4c6976cf334ba281017d0eac64  scripts/lib/handlers/spec-inputs-digest.js
+9daeb255ff23b1b7831806200d2d5e4c  scripts/lib/handlers/spec-predates-plan.js
+ee73864570c04d3c420b824b700e9b7c  scripts/lib/handlers/stories-lacking-spec.js
+ac166207d8a1d93a4c50a88568ef6e5c  scripts/lib/handlers/write-missing-plans.js
+9038bc6d4e70462f757ee5e544df9c78  scripts/lib/codeline-packages.js
+3fedc22f90f05ca8740686295bb79d07  scripts/lib/ecosystem-registry.js
+9c0c8864b3cd98826fd930fdc5193d01  scripts/lib/plan-hash.js
+8a1bb4df2d1b6e7fd135f757423fb2f2  config/repo-artifacts.json
+91cec3c50040ebc9050c3d95f037bce2  config/run-modes.json
+ee4366721c38cbc8cd72ee0f779d22a8  scripts/lib/plan-scope.js
+aab7063cf68a9ecd54f6ef735adf895e  scripts/lib/engine-paths.sh
+1d0346da09c13150e511809034396949  scripts/lib/pipeline-commit.sh

package/docs/gateway-files.txt

@@ -1,6 +1,9 @@
 config/doctor-heavy-jobs.json
 config/doctor-signatures.json
 config/model-pricing.json
+config/repo-artifacts.json
+config/resume-preserves.json
+config/run-modes.json
 prompts/doctor-repair.md
 prompts/templates/codeline-discovery.json
 scripts/agent-attempt-analyst.sh
@@ -8,9 +11,15 @@ scripts/lib/agent-contract.js
 scripts/lib/agent-ladder.sh
 scripts/lib/agent-messages.js
 scripts/lib/agent-si.js
+scripts/lib/checkpoints.sh
+scripts/lib/codeline-lanes.sh
+scripts/lib/codeline-packages.js
+scripts/lib/codeline-write-perimeter.sh
+scripts/lib/common.sh
 scripts/lib/constraint-compiler.js
 scripts/lib/constraint-sanity.js
 scripts/lib/content-retry.js
+scripts/lib/control-plane.sh
 scripts/lib/cost-emitter.js
 scripts/lib/cost-record.sh
 scripts/lib/doctor/agent.js
@@ -22,11 +31,37 @@ scripts/lib/doctor/profile.js
 scripts/lib/doctor/repair.js
 scripts/lib/doctor/restarter.js
 scripts/lib/doctor/state.js
+scripts/lib/ecosystem-registry.js
+scripts/lib/engine-paths.sh
 scripts/lib/engine-prompt.js
 scripts/lib/env-file.sh
 scripts/lib/evidence-windows.js
 scripts/lib/failure-signature.js
+scripts/lib/flags.sh
+scripts/lib/git-ops.sh
+scripts/lib/halt-recovery.sh
+scripts/lib/handlers/_read-input.js
+scripts/lib/handlers/carry-plan.js
+scripts/lib/handlers/cl-entries.js
+scripts/lib/handlers/codeline-ecosystem.js
+scripts/lib/handlers/codeline-manifests.js
 scripts/lib/handlers/emit-cost.js
+scripts/lib/handlers/filtered-prd.js
+scripts/lib/handlers/merge-lane-into-canonical.js
+scripts/lib/handlers/package-engines-node.js
+scripts/lib/handlers/prd-phases.js
+scripts/lib/handlers/rebuild-cross-contract.js
+scripts/lib/handlers/record-declared-pass.js
+scripts/lib/handlers/release-line-prd.js
+scripts/lib/handlers/release-lines.js
+scripts/lib/handlers/repo-exclude-patterns.js
+scripts/lib/handlers/resume-spec-output-present.js
+scripts/lib/handlers/sibling-providers.js
+scripts/lib/handlers/spanning-stories-incomplete.js
+scripts/lib/handlers/spec-inputs-digest.js
+scripts/lib/handlers/spec-predates-plan.js
+scripts/lib/handlers/stories-lacking-spec.js
+scripts/lib/handlers/write-missing-plans.js
 scripts/lib/jq-vals.sh
 scripts/lib/kb-apply.sh
 scripts/lib/kb-arbitration.js
@@ -37,15 +72,27 @@ scripts/lib/langfuse-emit.js
 scripts/lib/llm-settings-resolve.js
 scripts/lib/model-ladder.sh
 scripts/lib/model-ladders.sh
+scripts/lib/orchestration-resume.sh
+scripts/lib/phase-exit.sh
+scripts/lib/pipeline-commit.sh
 scripts/lib/pipeline-tools.js
+scripts/lib/plan-hash.js
+scripts/lib/plan-scope.js
 scripts/lib/preflight.sh
 scripts/lib/prelaunch.js
+scripts/lib/qa-gate-evidence.sh
 scripts/lib/relative-paths.js
+scripts/lib/release-lines.sh
 scripts/lib/render-prompt-section.js
+scripts/lib/resume-semantics.sh
+scripts/lib/run-checkpoint.sh
+scripts/lib/run-modes.sh
 scripts/lib/seam-invocation.js
 scripts/lib/seam-ladder.sh
 scripts/lib/self-heal.js
 scripts/lib/stage-coverage-gate.sh
+scripts/lib/story-outputs.sh
+scripts/lib/story-retry-state.sh
 scripts/lib/tool-timeouts.js
 scripts/lib/transcript-tool-calls.js
 scripts/llm-handler.sh

package/orchestrations/config/repo-artifacts.json

@@ -0,0 +1,23 @@
+{
+  "$comment": "Directories and files that are never agent output, and are not facts of any ecosystem. Ecosystem artefacts (node_modules, target, __pycache__, .venv …) live in scripts/lib/ecosystem-registry.js beside the ecosystem that produces them; these are editor and operating-system droppings, and engine state that must never reach a client repository. Extracted 2026-08-16 from two hand-written lists — one in worktree-health-check.sh and one in lib/git-ops.sh — that had drifted apart and between them named only node_modules, build and .next.",
+
+  "$biasComment": "The bias here is deliberate and one-directional. A directory wrongly EXCLUDED loses real agent work silently; one wrongly INCLUDED appears in a diff where a human sees it. So this list stays short and holds only what can never be source. Anything ambiguous belongs in the repository's own .gitignore, which is the customer's decision to make, not the engine's.",
+
+  "dirs": [
+    ".idea",
+    ".vscode",
+    ".dart_tool"
+  ],
+
+  "files": [
+    ".DS_Store",
+    "Thumbs.db"
+  ],
+
+  "$engineComment": "Engine state, matched as path prefixes. The write perimeter in lib/engine-paths.sh is the authority and is applied separately; these are the belt-and-braces entries the untracked report also needs, so an engine file never shows up as the agent's uncommitted work.",
+  "enginePaths": [
+    "orchestrations/logs/*",
+    "orchestrations/prd.json.lock",
+    "orchestrations/prd.json.backup"
+  ]
+}

package/orchestrations/config/resume-preserves.json

@@ -0,0 +1,25 @@
+{
+  "$why": [
+    "Between 2026-09-15 and 2026-09-20 five components each had to be taught 'this is a resume'",
+    "separately, one live failure at a time: the launcher tore the codeline down, the lifecycle",
+    "passed --reset, pre-run-reset archived the run's ledgers, pre-flight refused the run's own",
+    "spec blocks and healing ledger, and the remediation reset 14 completed stories ($20). Each",
+    "read EPAM_RESUME_RUN on its own and decided on its own what that meant. This file is the",
+    "one statement of what a resume keeps; lib/resume-semantics.sh (and its Python twin) answers",
+    "resume_preserves <aspect> from it; every consumer asks. An aspect not listed here is refused",
+    "loudly by the reader — never guessed."
+  ],
+  "preserves": {
+    "prd-state": "The PRD on disk is the run's own working copy — never restored from the authored canonical (tier3-run 2026-09-16, pre-flight 2026-09-15).",
+    "codeline": "The output directory holds the run's committed work; it is not torn down or reinitialised (tier3-run 2026-09-16).",
+    "ledgers": "phase-gates, phase-cost, healing-events, run-guidance, code-reviews and the other JSONL ledgers under LOG_DIR, and the per-story writer-rung (story-rung/) and ladder-state (story-retry-state/) records, are this run's record — not archived or cleared (pre-run-reset 2026-09-18 and 2026-09-21, pre-flight 2026-09-19).",
+    "roster": "The roster and agent profiles this run minted and reviewed are reused byte-for-byte; the specialiser is not called again (pre-run-reset 2026-09-19). Also across an engine release between pause and resume: an entry whose canonical ancestor changed is kept as reviewed and a canonical agent the release added is adopted verbatim, both recorded in logs/roster-release-drift.json — the roster is never re-derived (lib/project-roster.js keptAcrossRelease, 2026-09-25).",
+    "prompts": "The prompt set built for this run's codeline is reused, not rebuilt (2026-09-19) — except that when its inputs changed since, each kept generated prompt is judged again by the current reviewer and only one the reviewer rejects is regenerated (operator, 2026-10-06).",
+    "fetched-documents": "Referenced documents and the estate survey fetched for this run are kept (pre-run-reset 2026-09-18).",
+    "phase-gates": "A phase whose gate already decided GO is recognised as completed and not run again (greenfield-lifecycle 2026-09-16).",
+    "completed-stories": "A story marked completed keeps its status and record; only failed, blocked or in-progress stories are re-queued; the orchestrator runs without --reset (greenfield-lifecycle 2026-09-16, prd-remediate 2026-09-20).",
+    "spec-blocks": "Specification blocks on pending stories are this run's own spec pass, not prior-run contamination (prd-remediate and pre-flight 2026-09-15).",
+    "checkpoint": "The run's checkpoint (roster, prompts, PRD, briefs) is restored and owned by this run; a later launch may displace, never overwrite (run-checkpoint 2026-09-19).",
+    "review-findings": "The reviewer's per-story findings (review-feedback-<story>.json) are this run's own evidence; the story a resume re-runs is the one they reject, and the writer is re-invoked with them (pre-run-reset 2026-09-22)."
+  }
+}

package/orchestrations/config/run-modes.json

@@ -0,0 +1,47 @@
+{
+  "_what": "Named run modes. A mode is a stated INTENT — 'resume the writer' — and the set of steps that intent turns off.",
+  "_why": [
+    "On 2026-08-13 an operator asked for a writer resume. It was launched with three environment",
+    "variables and needed six, so the CPA pre-pass, the pre-phase skill assessment and the",
+    "regression guard all ran anyway — each is a separate default-ACTIVE step, and nothing tied",
+    "any of them to the stated intent. The operator had to notice it mid-run.",
+    "",
+    "The intent already existed in run-checkpoint.sh's pre-writer stage, reachable only through a",
+    "checkpoint, and even that list omitted the regression guard. Two half-definitions of one idea.",
+    "",
+    "Declared here, the engine reads a mode and never knows one. Adding a mode is an edit to this",
+    "file. Nobody assembles a mode by hand, so no mode can be half-applied."
+  ],
+  "modes": {
+    "writer-only": {
+      "_what": "Resume at the writer. The spec pass, roster mint, Jira ingest, CPA pre-pass, pre-phase skill assessment and regression baseline have all already run, or are not wanted for this attempt.",
+      "_cost": "Skipping the regression baseline means later test gates judge the codeline's CURRENT state, so pre-existing failures can be attributed to this change. Right for testing a writer; wrong for a run you intend to merge.",
+      "skips": [
+        "EPAM_SPEC_MODE=0",
+        "EPAM_SKIP_AGENT_MINT=1",
+        "EPAM_SKIP_JIRA_INGEST=1",
+        "SKIP_CPA=1",
+        "SKIP_SKILL_ASSESSMENT=1",
+        "SKIP_REGRESSION_GUARD=true"
+      ],
+      "_why_no_mint": "The mint does NOT run. A writer re-run uses the roster that was already minted and reviewed; re-minting proposes against an existing roster and the merge is additive, so it accumulates near-duplicate roles and changes the agents under a story mid-stream."
+    },
+    "post-spec": {
+      "_what": "The spec pass and the roster are done and on disk; everything from the CPA pre-pass onward still runs.",
+      "skips": [
+        "EPAM_SPEC_MODE=0",
+        "EPAM_SKIP_JIRA_INGEST=1",
+        "EPAM_SKIP_AGENT_MINT=1"
+      ],
+      "_why_mint": "Skips the mint because this mode describes a RESUME of a run whose roster is already on disk — pre-run-reset preserves the registries when EPAM_RESUME_RUN is set. A fresh launch has no such protection, which is why writer-only does not skip it."
+    },
+    "post-roster": {
+      "_what": "The roster is minted and assignments are written; the spec pass still runs.",
+      "skips": [
+        "EPAM_SKIP_JIRA_INGEST=1",
+        "EPAM_SKIP_AGENT_MINT=1"
+      ],
+      "_why_mint": "Skips the mint because this mode describes a RESUME of a run whose roster is already on disk — pre-run-reset preserves the registries when EPAM_RESUME_RUN is set. A fresh launch has no such protection, which is why writer-only does not skip it."
+    }
+  }
+}

package/orchestrations/scripts/lib/checkpoints.sh

@@ -0,0 +1,175 @@
+#!/usr/bin/env bash
+# checkpoints.sh — moved verbatim out of run-agent-orchestration.sh by tools/split-main-into-modules.py
+# (6 functions). Sourced by run-agent-orchestration.sh; SCRIPT_DIR and the globals it sets
+# are in scope exactly as they were. A move, not an edit: every body is byte-identical to
+# the golden recorded at the move (see the identity test).
+
+# ── GAP-P13 checkpoint helpers ──────────────────────────────────────────────
+# Write a completed checkpoint entry for a story.
+checkpoint_complete() {
+    local story_id="$1"
+    local idem_key="${ORCH_RUN_ID}:${PHASE:-main}:${story_id}"
+    jq -cn \
+        --arg key   "$idem_key" \
+        --arg sid   "$story_id" \
+        --arg phase "${PHASE:-main}" \
+        --arg runId "$ORCH_RUN_ID" \
+        '{idempotencyKey:$key, storyId:$sid, phase:$phase, runId:$runId,
+          status:"completed", completedAt:(now|todate)}' \
+        >> "$CHECKPOINT_FILE" 2>/dev/null || true
+}
+
+# Returns 0 (true) if the story already has a completed checkpoint in this run.
+# Used to skip stories that finished before a crash/restart.
+checkpoint_already_done() {
+    local story_id="$1"
+    [ ! -f "$CHECKPOINT_FILE" ] && return 1
+    local idem_key="${ORCH_RUN_ID}:${PHASE:-main}:${story_id}"
+    grep -q "\"idempotencyKey\":\"${idem_key}\"" "$CHECKPOINT_FILE" 2>/dev/null
+}
+
+# Clear checkpoints for this phase+run (called when RESET_STORIES=true).
+checkpoint_clear() {
+    rm -f "$CHECKPOINT_FILE" 2>/dev/null || true
+}
+
+# RESUME IS DECIDED BEFORE ANY WORK, NOT AFTER IT.
+#
+# EPAM_RESUME_RUN restores what a previous run persisted and skips exactly what that
+# checkpoint already paid for — derived from the stage it was taken at, never assumed.
+#
+# This block used to sit past the entry-point dispatch below, and a Jira run calls
+# _run_jira_pipeline and EXITS there, so on that shape it was never reached. The checkpoint was
+# never restored and the skip env was computed for a branch that never ran. Every "resume" was
+# therefore a fresh run: it re-ingested, re-minted, and discarded the roster the operator had
+# just reviewed at the pause — which made the roster pause ceremonial, since you reviewed one
+# roster and ran a different one.
+#
+# A resume that cannot be honoured HALTS. Continuing would silently run against whatever stale
+# state happened to be on disk, which is the failure this exists to prevent.
+#
+# Top level only: lanes re-invoke this script and would each restore the checkpoint over their
+# own state. The parent decides what to resume; the lanes inherit the result.
+# resume_spec_output_present <prd_file>
+# Did the spec pass leave anything behind in this PRD?
+#
+# A resume exports EPAM_SPEC_MODE=0 to mean "the spec pass already ran, skip it". That is a
+# statement about HISTORY, and history stops being a safe proxy the moment something overwrites
+# the PRD in between. Live 2026-08-10: a fresh (non-resume) launch re-ingested Jira over the
+# same file, emptying fixSiteAnalysis (13->0), verificationCriteria (14->0) and the declared
+# file list (13->0). The next resume skipped the spec pass exactly as instructed and handed the
+# writer a story with nothing to aim at — 23 invocations, 10 watchdog kills, $11.76, no code.
+#
+# PRESENCE, not content: any one of the spec pass's own output fields being non-empty proves it
+# ran and survived. Nothing here names a story, a file, a codeline or a project, so a PRD from
+# any project passes the moment its spec pass has left something behind.
+#
+# Fails CLOSED — unreadable, absent or malformed all count as "not present". A guard against
+# missing state must not treat "I could not tell" as "fine".
+resume_spec_output_present() {
+    local _prd="${1:-}"
+    [ -n "$_prd" ] && [ -f "$_prd" ] || return 1
+    "${NODE_BIN:-node}" "$SCRIPT_DIR/lib/handlers/resume-spec-output-present.js" "$_prd" 2>/dev/null
+}
+
+# _clear_suite_state_for_phase <prd_file> <phase>
+# WHATEVER SETS THE FLAG CAN UNSET IT.
+#
+# Step 3.545 stamps suiteState=red when it cannot reconcile a failing test, and Step 3.55
+# blocks on that flag. Nothing ever cleared it, so it was a latch: a run that recovered was
+# still failed by its own history.
+#
+# Live, run 20260815T142007Z (metrolinx, AMSD-2041): pass 1's generated spec mocked a module
+# the SDK does not use, the suite went red, and 3.545 stamped it. The retry fixed the code —
+# tsc passed, external verification passed, the story completed and committed. At 16:03
+# update-invalidated-tests re-checked and reported "suite already green — nothing to do",
+# and seconds later Step 3.55 failed the phase on the stale flag, asserting "Step 3.545
+# could not reconcile it" about a step that had just reported the opposite. The suite was
+# green: 1203/1203 under the project's declared TZ.
+#
+# This ONLY clears. Step 3.55 is untouched, so a suite that never recovered still blocks —
+# that is the behaviour the flag exists to provide.
+_clear_suite_state_for_phase() {
+    local _prd="${1:-}" _phase="${2:-}"
+    [ -f "$_prd" ] || return 0
+    local _ids
+    _ids=$(jq -r --arg phase "$_phase" '(.implementationOrder[$phase] // [])[]?' "$_prd" 2>/dev/null)
+    [ -n "$_ids" ] || return 0
+    local _sid
+    while IFS= read -r _sid; do
+        [ -n "$_sid" ] || continue
+        jq -e --arg id "$_sid" '.stories[] | select(.id == $id) | has("suiteState")' "$_prd" >/dev/null 2>&1 || continue
+        local _tmp
+        _tmp="$(mktemp)"
+        # Staged through a temp file and moved: a truncated PRD is worse than a stale flag.
+        if jq --arg id "$_sid" \
+            '(.stories[] | select(.id == $id)) |= (del(.suiteState) | del(.suiteStateStep))' \
+            "$_prd" > "$_tmp" 2>/dev/null; then
+            mv "$_tmp" "$_prd"
+            info "Step 3.545: suite recovered — cleared suiteState on $_sid"
+        else
+            rm -f "$_tmp"
+        fi
+    done <<< "$_ids"
+    return 0
+}
+
+# ──────────────────────────────────────────────
+# run_interstitial_e2e_phase <phase_id>
+# Step 5.5: After phase gate passes, check for a <phase_id>_e2e phase
+# in implementationOrder and run it. Blocks next phase if E2E fails.
+# ──────────────────────────────────────────────
+run_interstitial_e2e_phase() {
+    local phase_id="$1"
+    local e2e_phase="${phase_id}_e2e"
+
+    local has_e2e_phase
+    has_e2e_phase=$(jq -r --arg p "$e2e_phase" \
+        'if .implementationOrder[$p] then "yes" else "no" end' \
+        "$PRD_FILE" 2>/dev/null || echo "no")
+
+    if [ "$has_e2e_phase" = "no" ]; then
+        info "Step 5.5: No interstitial E2E phase for '$phase_id' — skipping"
+        return 0
+    fi
+
+    log "Step 5.5: Running interstitial E2E phase '$e2e_phase'..."
+    "$SCRIPT_DIR/update-monitor.sh" event "e2e_gate_start" \
+        "Starting E2E phase $e2e_phase" "" "main" "qa-engineer" 2>/dev/null || true
+
+    local e2e_log="$LOG_DIR/e2e-phase-${e2e_phase}.log"
+    # PIPESTATUS[0], NOT THE `if`. Without pipefail -- and this script sets none -- `if cmd | tee`
+    # tests TEE's status, which is always 0. So this phase reported PASSED unconditionally and the
+    # else branch below, which fails the run, was unreachable. Same defect as the phase gate.
+    bash "$0" --phase "$e2e_phase" 2>&1 | tee "$e2e_log"
+    local _e2e_rc=${PIPESTATUS[0]}
+    if [ "$_e2e_rc" -eq 0 ]; then
+        success "Interstitial E2E phase '$e2e_phase' PASSED"
+        "$SCRIPT_DIR/update-monitor.sh" event "e2e_gate_pass" \
+            "E2E phase $e2e_phase passed" "" "main" "qa-engineer" 2>/dev/null || true
+    else
+        local e2e_exit=$_e2e_rc
+        error "Interstitial E2E phase '$e2e_phase' FAILED (exit $e2e_exit)"
+        error "Fix E2E failures then re-run: $0 --phase $e2e_phase"
+        error "Log: $e2e_log"
+        "$SCRIPT_DIR/update-monitor.sh" event "e2e_gate_fail" \
+            "E2E phase $e2e_phase FAILED" "" "main" "qa-engineer" 2>/dev/null || true
+        return 1
+    fi
+}
+
+# record_run_pause <stage>
+# THE PAUSE, ON DISK, FOR THE LAUNCHER. A pause exits 0 — it is not a failure — and the greenfield
+# phase loop read that 0 as "phase completed", started the next phase, minted a second run id and
+# reported the project done (run 20260916T200051Z → 200108Z). The launcher cannot tell a pause
+# from a completion by exit code alone, so the pause says so here: run id, stage and phase, in
+# the run's log dir, where the loop looks after every phase.
+record_run_pause() {
+    local _stage="${1:?stage}"
+    local _dir="${EPAM_PROJECT_OUTPUT_DIR:-${LOG_DIR:-}}"
+    [ -n "$_dir" ] || return 0
+    mkdir -p "$_dir" 2>/dev/null || return 0
+    jq -n --arg runId "${ORCH_RUN_ID:-}" --arg stage "$_stage" --arg phase "${PHASE:-}" --arg at "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+        '{runId:$runId, stage:$stage, phase:$phase, pausedAt:$at}' > "$_dir/paused-run.json" 2>/dev/null || true
+}
+