amsd-pipeline-shared 0.3.0 → 0.4.0

package/bin/amsd-pipeline-shared.js

@@ -6,6 +6,7 @@
 //   amsd-pipeline-shared verify  --into <install>   every file is this package's (exit 1 and the list when not)
 //   amsd-pipeline-shared revert  --into <install>   put back the files this package replaced
 //   amsd-pipeline-shared messages send|receive|list --dir <bus> …   the agent-to-agent bus (lib/agent-messages.js)
+//   amsd-pipeline-shared prelaunch --install <i> --project <p> --run-id <id> --out <dir> …   the shared pre-launch
 //   amsd-pipeline-shared version
 // A file is replaced only when the install holds the released copy this package was built from (docs/gateway-baseline-
 // 2.0.80.md5) or this package's own copy (a re-install); anything else is refused, file by file, and nothing is written.
@@ -23,6 +24,8 @@ const fail = (m, code = 1) => { process.stderr.write(`amsd-pipeline-shared: ${m}
 
 const [cmd, ...rest] = process.argv.slice(2);
 if (cmd === 'version') { process.stdout.write(`${PKG.version}\n`); process.exit(0); }
+// THE SHARED PRE-LAUNCH, for every pipeline (lib/prelaunch.js): amsd-pipeline-shared prelaunch --install <i> --project <p> …
+if (cmd === 'prelaunch') process.exit(require(path.join(ROOT, 'orchestrations', 'scripts', 'lib', 'prelaunch.js')).prelaunchCli(rest));
 // THE MESSAGE BUS FOR SHELL CALLERS (the bash pipeline's adoption, backlog B55): one JSON line out
 if (cmd === 'messages') {
   const m = require(path.join(ROOT, 'orchestrations', 'scripts', 'lib', 'agent-messages.js'));

package/docs/gateway-baseline-2.0.80.md5

@@ -24,6 +24,7 @@ c0a3a88d1a895e0a86ea483cada15411  scripts/lib/kb-store.js
 ed15fbd317db2643b19a3fd7ecd1979a  scripts/lib/model-ladder.sh
 4d2dc2a636736b5b77711ad7736f9075  scripts/lib/model-ladders.sh
 97d25b9108a01292d1b28da0d3c129e9  scripts/lib/pipeline-tools.js
+c806c7a54ebfb7ea178ef8415bb70c1c  scripts/lib/preflight.sh
 6bfffd3ba6eb845f738d3157168bf056  scripts/lib/relative-paths.js
 6894e248c7a86d07626b7e981d534354  scripts/lib/render-prompt-section.js
 912511e457b0a6f4801c479400b1c3a3  scripts/lib/seam-invocation.js
@@ -33,6 +34,9 @@ ed15fbd317db2643b19a3fd7ecd1979a  scripts/lib/model-ladder.sh
 be6d0a378fa9c3bc9da6240877aaeae3  scripts/lib/tool-timeouts.js
 5574182fb27aaeabbfff261b3a8d6d39  scripts/lib/transcript-tool-calls.js
 c4b96230c15b52a845cf20fd3266fe01  scripts/llm-handler.sh
+9b05c5b99b4f803c3a568ce5c069e6d3  scripts/preflight-check.sh
+740a55fe2ae0527a0598f3c751bacca7  scripts/preflight-prd-integrity.sh
+bc5acdb9260923082e05ef3b67304028  scripts/preflight-static.sh
 f206025f304e8320b8417a6dd6606044  scripts/spec-mode-runner.js
 dfa070b168a7c01fab8aab5a46d16192  scripts/team-lead-review.sh
 40c65de8360d5a9f59902fca26d1d7a8  scripts/update-monitor.sh

package/docs/gateway-files.txt

@@ -25,6 +25,8 @@ scripts/lib/llm-settings-resolve.js
 scripts/lib/model-ladder.sh
 scripts/lib/model-ladders.sh
 scripts/lib/pipeline-tools.js
+scripts/lib/preflight.sh
+scripts/lib/prelaunch.js
 scripts/lib/relative-paths.js
 scripts/lib/render-prompt-section.js
 scripts/lib/seam-invocation.js
@@ -34,6 +36,9 @@ scripts/lib/stage-coverage-gate.sh
 scripts/lib/tool-timeouts.js
 scripts/lib/transcript-tool-calls.js
 scripts/llm-handler.sh
+scripts/preflight-check.sh
+scripts/preflight-prd-integrity.sh
+scripts/preflight-static.sh
 scripts/spec-mode-runner.js
 scripts/team-lead-review.sh
 scripts/update-monitor.sh

package/orchestrations/scripts/lib/preflight.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# preflight.sh — run the pre-launch assessment from any launcher, with no launcher having
+# to know the check script's arguments.
+#
+# preflight-check.sh existed with six sections and was wired into exactly TWO of the eight
+# launchers. The two being run daily (metrolinx, mock) were not among them, which is why
+# four separate launch failures on 2026-08-05 — a stale dist twice, a dead observability
+# stack, a project with no synthesis template — were each discovered by spending a launch
+# instead of by the check that exists to prevent exactly that.
+#
+# The runner name and the project config directory are DERIVED here rather than passed:
+# a launcher that had to repeat them is a launcher that can get them wrong, and one already
+# did — tier3-skyscanner-app-run.sh passed --runner tier3-travel-app-run.sh, so it
+# pre-flighted a different launcher than the one it was about to run.
+#
+# Usage:  . lib/preflight.sh ; require_preflight   # aborts the launch if anything fails
+
+require_preflight() {
+  local script_dir="${SCRIPT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+  local check="$script_dir/preflight-check.sh"
+
+  if [ ! -f "$check" ]; then
+    echo "  ✗ preflight-check.sh not found at $check — refusing to launch unassessed" >&2
+    return 1
+  fi
+
+  local -a args=()
+  # The runner is whichever launcher sourced this file. $0 is that launcher.
+  args+=(--runner "$(basename "${0:-unknown}")")
+  [ -n "${PRD_FILE:-}" ] && args+=(--prd "$PRD_FILE")
+  [ -n "${EPAM_PROJECT_CONFIG_DIR:-}" ] && args+=(--project-config "$EPAM_PROJECT_CONFIG_DIR")
+
+  echo "── Pre-flight assessment ─────────────────────────────────────────────────────"
+  if bash "$check" "${args[@]}"; then
+    # THE SHARED PRE-LAUNCH (amsd-pipeline-shared, operator 2026-10-19: one pre-launch for every pipeline): the checks
+    # every launch owes after the pipeline's own — Langfuse, the seeded ticket, the codeline cache, cost, nothing else
+    # running, memory, no clock above an agent, the 12-item checklist. Skipped only when it is the shared pre-launch
+    # that is running these checks (AMSD_PRELAUNCH_INNER), so the two never loop.
+    [ "${AMSD_PRELAUNCH_INNER:-}" = "1" ] && return 0
+    local _pl="$script_dir/lib/prelaunch.js" _install _plargs=()
+    _install="$(cd "$script_dir/../.." && pwd)"
+    if [ ! -f "$_pl" ]; then
+      echo "  ✗ the shared pre-launch is not installed ($_pl) — refusing to launch unassessed" >&2
+      return 1
+    fi
+    _plargs=(--install "$_install" --project "$(basename "${EPAM_PROJECT_CONFIG_DIR:-${PROJECT_CONFIG_DIR:-unknown}}")"
+             --run-id "${ORCH_RUN_ID:-prelaunch-$(date -u +%Y%m%dT%H%M%SZ)}" --out "${LOG_DIR:-$_install/orchestrations/logs}/prelaunch"
+             --runner "$(basename "${0:-unknown}")" --preflight no)
+    [ -n "${JIRA_TICKET:-}" ] && [ -n "${AMSD_PRELAUNCH_RUNS:-}" ] && _plargs+=(--ticket "$JIRA_TICKET" --runs "$AMSD_PRELAUNCH_RUNS")
+    [ -n "${EPAM_CODELINE_ID:-}" ] && _plargs+=(--codeline "$EPAM_CODELINE_ID")
+    [ -n "${EPAM_PROVIDER_SET:-}" ] && _plargs+=(--set "$EPAM_PROVIDER_SET")
+    if "${NODE_BIN:-node}" "$_pl" "${_plargs[@]}"; then
+      return 0
+    fi
+    echo "" >&2
+    echo "  ✗ Pre-launch FAILED — aborting before spending. Fix the items above." >&2
+    return 1
+  fi
+
+  # Deliberately not skippable by an env var. Every failure this catches cost a launch
+  # cycle or credits; an escape hatch here would be used on the run that needed it most.
+  echo "" >&2
+  echo "  ✗ Pre-flight FAILED — aborting before spending. Fix the items above." >&2
+  return 1
+}

package/orchestrations/scripts/lib/prelaunch.js

@@ -0,0 +1,294 @@
+'use strict';
+// THE PRE-LAUNCH, SHARED BY EVERY PIPELINE (operator, 2026-10-19: "Make pre-launch a common component. It needs to be
+// shared between all pipelines."). Before any model call: the pipeline's own pre-flight (preflight-check.sh through
+// lib/preflight.sh require_preflight, unchanged) and the checks the operator approved the same day, each from a failure
+// that reached a live launch:
+//   1 langfuse      Langfuse answers and a launch trace is written and read back under the run's session id
+//   2 seed          the seeded prompts and agent files are the launched ticket's (byte-identical to a recorded run of it)
+//   3 cache         the codeline cache carries both layers: the prompt set and the per-prompt entries the builder reuses
+//   4 cost          the ledger writer records a priced call, and every model on the active ladders has a price
+//   5 alone         no other pipeline run or test is working against this install
+//   6 memory        the host can give the run what it needs and keep 3 GB for itself
+//   7 no-timeout    nothing above the launch can cut an agent off on a clock
+//   8 checklist     the operator's 12-item run checklist, scored: green / red / not-yet (decided in the run)
+// Each check returns {name, ok, detail}; nothing here makes a model call. Any red stops the launch.
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { spawnSync } = require('child_process');
+
+const md5 = (f) => crypto.createHash('md5').update(fs.readFileSync(f)).digest('hex');
+const readJson = (f, d = null) => { try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return d; } };
+const orchOf = (install) => path.join(install, 'orchestrations');
+const scriptsOf = (install) => path.join(orchOf(install), 'scripts');
+const res = (name, ok, detail, extra = {}) => ({ name, ok: !!ok, detail, ...extra });
+
+// ── 0. the pipeline's own pre-flight, unchanged ──────────────────────────────────────────────────────────────────────
+function preflight({ install, env, runner, prd }) {
+  const sd = scriptsOf(install);
+  // require_preflight names the runner from $0 (the launcher that sourced it): the runner's own name is passed as $0
+  // AMSD_PRELAUNCH_INNER: require_preflight runs this pre-launch after its own checks (every bash launcher); called from
+  // here, it runs the pipeline's checks alone — no loop
+  const r = spawnSync('bash', ['-c', '. "$1/lib/preflight.sh" && require_preflight', runner || 'orchestrate.sh', sd],
+    { env: { ...env, SCRIPT_DIR: sd, AMSD_PRELAUNCH_INNER: '1', ...(prd ? { PRD_FILE: prd } : {}) }, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024 });
+  const out = `${r.stdout || ''}${r.stderr || ''}`;
+  const failed = (out.match(/^\s*✗ .*$/gm) || []).map((l) => l.trim());
+  return res('preflight', r.status === 0, r.status === 0 ? `the pipeline's pre-flight passed (${(out.match(/^\s*✓ /gm) || []).length} checks)` : `${failed.length} failed: ${failed.slice(0, 6).join(' | ')}`, { log: out });
+}
+
+// ── 1. langfuse ──────────────────────────────────────────────────────────────────────────────────────────────────────
+/** The install's LANGFUSE_* settings, added to `env` where `env` has none. */
+function langfuseEnv(install, env) {
+  const out = { ...env };
+  for (const l of (fs.existsSync(path.join(install, '.env')) ? fs.readFileSync(path.join(install, '.env'), 'utf8') : '').split('\n')) {
+    const m = l.match(/^(LANGFUSE_[A-Z_]+)=(.*)$/); if (m && !out[m[1]]) out[m[1]] = m[2].replace(/^["']|["']$/g, '');
+  }
+  return out;
+}
+function langfuse({ install, env, runId, outDir, traceName = 'launch-prelaunch', waitMs = 2000, tries = 6 }) {
+  const e = langfuseEnv(install, env);
+  const lf = require(path.join(scriptsOf(install), 'lib', 'langfuse-emit.js'));
+  const cfg = lf.config(e);
+  const probe = cfg ? spawnSync('curl', ['-s', '-o', '/dev/null', '-w', '%{http_code}', '--max-time', '5', `${cfg.base}/api/public/health`], { encoding: 'utf8' }).stdout : '';
+  if (probe !== '200') return res('langfuse', false, `Langfuse is required and is not answering (${cfg ? `${cfg.base} → ${probe || 'no answer'}` : 'not configured: no keys or endpoint'})`);
+  const session = lf.sessionId({ ...e, ORCH_RUN_ID: runId });
+  fs.mkdirSync(outDir, { recursive: true });
+  const marker = path.join(outDir, `langfuse-${traceName}.js`);
+  fs.writeFileSync(marker, `require(${JSON.stringify(path.join(scriptsOf(install), 'lib', 'langfuse-emit.js'))}).emitGeneration({ agent: ${JSON.stringify(traceName)}, model: 'none', costUsd: 0, tokensIn: 0, tokensOut: 0, input: ${JSON.stringify(`pre-launch of ${runId}`)}, output: 'launch' }, process.env).then((ok) => process.exit(ok ? 0 : 1))`);
+  const sent = spawnSync(process.execPath, [marker], { env: { ...process.env, ...e, ORCH_RUN_ID: runId }, encoding: 'utf8' }).status === 0;
+  let found = 0;
+  for (let i = 0; i < tries && sent && !found; i += 1) {
+    spawnSync('sleep', [String(waitMs / 1000)]);
+    const q = spawnSync('curl', ['-s', '--max-time', '5', '-u', `${e.LANGFUSE_PUBLIC_KEY}:${e.LANGFUSE_SECRET_KEY}`, `${cfg.base}/api/public/traces?sessionId=${encodeURIComponent(session)}&name=${traceName}&limit=5`], { encoding: 'utf8' }).stdout;
+    try { found = (JSON.parse(q).data || []).filter((t) => t.sessionId === session && t.name === traceName).length; } catch { found = 0; }
+  }
+  return found ? res('langfuse', true, `trace '${traceName}' read back under session ${session} (${cfg.base})`, { session, base: cfg.base })
+    : res('langfuse', false, `no trace under Langfuse session ${session} could be read back (${sent ? 'sent, not found' : 'not sent'})`);
+}
+
+// ── 2. seed ──────────────────────────────────────────────────────────────────────────────────────────────────────────
+function seededFiles(install, project) {
+  const pcd = path.join(orchOf(install), 'projects', project);
+  const { MINTED_FILES } = require(path.join(scriptsOf(install), 'lib', 'project-prompt-builder.js'));
+  const out = []; const pd = path.join(pcd, 'prompts');
+  if (fs.existsSync(pd)) for (const f of fs.readdirSync(pd).filter((n) => n.endsWith('.json')).sort()) out.push({ rel: path.join('prompts', f), abs: path.join(pd, f), name: f, kind: 'prompt' });
+  for (const f of MINTED_FILES) if (fs.existsSync(path.join(pcd, f))) out.push({ rel: f, abs: path.join(pcd, f), name: f, kind: 'minted' });
+  return out;
+}
+const prdNames = (prd, ticket) => ((prd && (prd.stories || prd.userStories)) || []).some((s) => s && (s.id === ticket || s.jiraKey === ticket));
+function ticketSnapshots(runsRoots, ticket) {
+  const snaps = [];
+  for (const root of runsRoots) {
+    let runs = []; try { runs = fs.readdirSync(root); } catch { continue; }
+    for (const r of runs.sort()) {
+      const rd = path.join(root, r);
+      if (!prdNames(readJson(path.join(rd, 'checkpoint', 'prd.json')), ticket)) continue;
+      const walk = (d, depth) => {
+        if (depth > 6) return;
+        let ents = []; try { ents = fs.readdirSync(d, { withFileTypes: true }); } catch { return; }
+        for (const e of ents) if (e.isDirectory()) { const p = path.join(d, e.name); if (e.name === 'checkpoint') snaps.push({ run: rd, dir: p }); else walk(p, depth + 1); }
+      };
+      walk(rd, 0);
+    }
+  }
+  return snaps;
+}
+const snapshotCopy = (snap, f) => (f.kind === 'prompt' ? [path.join(snap.dir, 'prompts', f.name)] : [path.join(snap.dir, f.name), path.join(snap.dir, 'reviewed', f.name)]).find((p) => fs.existsSync(p)) || null;
+function seed({ install, project, ticket, runsRoots }) {
+  const files = seededFiles(install, project);
+  if (!files.length) return res('seed', false, 'nothing is seeded — no prompts and no minted files on disk');
+  const prefix = String(ticket).replace(/-\d+$/, '').replace(/[^A-Za-z0-9]/g, '');
+  const keyRe = new RegExp(`\\b${prefix}-\\d+\\b`, 'g');
+  const otherTickets = files.map((f) => ({ file: f.rel, keys: [...new Set((fs.readFileSync(f.abs, 'utf8').match(keyRe) || []).filter((k) => k !== ticket))] })).filter((o) => o.keys.length);
+  const snaps = ticketSnapshots(runsRoots, ticket);
+  if (!snaps.length) return res('seed', false, `no recorded run of ${ticket} under ${runsRoots.join(', ')}`, { otherTickets });
+  const best = snaps.map((s) => {
+    const mismatched = []; const unproven = []; let same = 0;
+    for (const f of files) { const c = snapshotCopy(s, f); if (!c) unproven.push(f.rel); else if (md5(c) === md5(f.abs)) same += 1; else mismatched.push(f.rel); }
+    return { s, same, mismatched, unproven };
+  }).sort((x, y) => y.same - x.same)[0];
+  const snapshot = path.relative(path.dirname(best.s.run), best.s.dir);
+  const ok = !best.mismatched.length && !best.unproven.length && !otherTickets.length;
+  const why = [best.mismatched.length && `${best.mismatched.length} differ from ${snapshot} (${best.mismatched.slice(0, 4).join(', ')})`,
+    best.unproven.length && `${best.unproven.length} have no copy in it`, otherTickets.length && `${otherTickets.length} name another ticket`].filter(Boolean).join('; ');
+  return res('seed', ok, ok ? `all ${files.length} seeded file(s) are ${ticket}'s (${snapshot}), no other ticket named` : `not proven ${ticket}'s: ${why}`,
+    { files: files.length, snapshot, mismatched: best.mismatched, unproven: best.unproven, otherTickets });
+}
+
+// ── 3. cache ─────────────────────────────────────────────────────────────────────────────────────────────────────────
+/**
+ * The prompts the builder GENERATES for a codeline, and so must find a per-prompt entry for to reuse: its own provisioning
+ * list, less the templates it installs as they are (copyVerbatim, and multi-body templates), present in the cached set.
+ * An entry is <cache>/<id>.json, or <id>.<variant>.json for a variant run (brownfield).
+ */
+function cache({ install, project, codeline, variant = process.env.EPAM_BROWNFIELD === '1' ? 'brownfield' : '' }) {
+  const O = orchOf(install);
+  const C = path.join(O, 'projects', project, '.prompt-cache', codeline);
+  const b = require(path.join(scriptsOf(install), 'lib', 'project-prompt-builder.js'));
+  const tpl = (t) => path.join(O, 'prompts', 'templates', `${t}.json`);
+  const problems = [];
+  const prompts = fs.existsSync(path.join(C, 'prompts')) ? fs.readdirSync(path.join(C, 'prompts')).filter((n) => n.endsWith('.json')).map((n) => n.replace(/\.json$/, '')) : [];
+  if (!prompts.length) problems.push(`no cached prompt set (${path.join(C, 'prompts')})`);
+  const minted = b.MINTED_FILES.filter((f) => !fs.existsSync(path.join(C, 'minted', f)));
+  if (minted.length) problems.push(`minted files missing: ${minted.join(', ')}`);
+  const marker = path.join(O, 'projects', project, '.prompt-cache', `.complete-${codeline}${variant ? `.${variant}` : ''}`);
+  if (!fs.existsSync(marker)) problems.push(`no completion marker ${path.basename(marker)}`);
+  const list = b.provisioningList({ bootstrap: readJson(path.join(O, 'prompts', 'bootstrap.json'), {}), registry: readJson(path.join(O, 'agents', 'invocation-profiles.json'), {}), templateExists: (t) => fs.existsSync(tpl(t)) });
+  const multi = (t) => Object.prototype.hasOwnProperty.call(readJson(tpl(t), {}), 'bodies');
+  const required = list.filter((i) => prompts.includes(i) && !multi(i));
+  const has = (i) => fs.existsSync(path.join(C, `${i}.json`)) || (variant && fs.existsSync(path.join(C, `${i}.${variant}.json`)));
+  const missing = required.filter((i) => !has(i));
+  if (missing.length) problems.push(`${missing.length} of ${required.length} generated prompt(s) have no per-prompt entry, so any template change rebuilds them all (${missing.slice(0, 5).join(', ')}${missing.length > 5 ? ', …' : ''})`);
+  return res('cache', !problems.length, problems.length ? problems.join('; ') : `${codeline}: ${prompts.length} cached prompt(s), ${b.MINTED_FILES.length} minted file(s), ${required.length} per-prompt entries, marker present`,
+    { required: required.length, missing });
+}
+
+// ── 4. cost ──────────────────────────────────────────────────────────────────────────────────────────────────────────
+/** Every model a provider set's ladders name (startModel, model, models, from/to), from its own declaration. */
+function ladderModels(install, set) {
+  const d = readJson(path.join(orchOf(install), 'config', `llm-defaults.${set}.json`), {});
+  const out = new Set();
+  const walk = (v, key) => {
+    if (Array.isArray(v)) { for (const x of v) walk(x, key); return; }
+    if (v && typeof v === 'object') { for (const [k, x] of Object.entries(v)) walk(x, k); return; }
+    if (typeof v === 'string' && /model|^from$|^to$/i.test(key || '')) out.add(v);
+  };
+  walk(d.ladders || {}, '');
+  return [...out].sort();
+}
+function cost({ install, set, tmpDir }) {
+  const problems = [];
+  // (a) the ledger writer records a priced call
+  const ledger = path.join(tmpDir, 'prelaunch-ledger.jsonl');
+  fs.mkdirSync(tmpDir, { recursive: true }); fs.rmSync(ledger, { force: true });
+  try {
+    const { appendLedgerRecord } = require(path.join(scriptsOf(install), 'lib', 'cost-emitter.js'));
+    appendLedgerRecord({ ledgerFile: ledger, agent: 'prelaunch-cost-probe', phase: 'prelaunch', model: 'prelaunch-probe', cost: { costUsd: 0.0123, tokensIn: 10, tokensOut: 5 } });
+    const rows = fs.readFileSync(ledger, 'utf8').trim().split('\n').filter(Boolean).map((l) => JSON.parse(l));
+    if (!(rows.length === 1 && Number(rows[0].task_cost_usd) === 0.0123)) problems.push(`the ledger writer did not record the probe's cost (${JSON.stringify(rows[0] || null).slice(0, 160)})`);
+  } catch (e) { problems.push(`the ledger writer failed: ${e.message}`); }
+  // (b) every ladder model is priced, so a call whose session never reports its cost (a killed leg) can still be priced
+  const prices = (readJson(path.join(orchOf(install), 'config', 'model-pricing.json'), {}) || {}).models || {};
+  const models = ladderModels(install, set);
+  const unpriced = models.filter((m) => !prices[m] || prices[m].inputPerMillion == null || prices[m].outputPerMillion == null);
+  if (!models.length) problems.push(`the ${set} set's ladders name no model`);
+  if (unpriced.length) problems.push(`no price in config/model-pricing.json for ladder model(s) ${unpriced.join(', ')} — a leg killed before its session reports a cost cannot be priced`);
+  return res('cost', !problems.length, problems.length ? problems.join('; ') : `the ledger records a priced call; all ${models.length} ladder model(s) priced`, { models, unpriced });
+}
+
+// ── 5. alone ─────────────────────────────────────────────────────────────────────────────────────────────────────────
+function ancestors(pid, procDir = '/proc') {
+  const out = new Set();
+  let p = String(pid);
+  for (let i = 0; i < 64 && p && p !== '0'; i += 1) {
+    out.add(p);
+    let st = ''; try { st = fs.readFileSync(`${procDir}/${p}/stat`, 'utf8'); } catch { break; }
+    p = st.slice(st.lastIndexOf(')') + 2).split(' ')[1];
+  }
+  return out;
+}
+const cmdline = (pid, procDir = '/proc') => { try { return fs.readFileSync(`${procDir}/${pid}/cmdline`, 'utf8').split('\0').filter(Boolean); } catch { return []; } };
+function alone({ install, selfPid = process.pid, procDir = '/proc' }) {
+  const mine = ancestors(selfPid, procDir);
+  const inst = path.resolve(install);
+  const others = [];
+  let pids = []; try { pids = fs.readdirSync(procDir).filter((n) => /^\d+$/.test(n)); } catch { pids = []; }
+  for (const p of pids) {
+    if (mine.has(p)) continue;
+    const a = cmdline(p, procDir); if (!a.length) continue;
+    const s = a.join(' ');
+    let cwd = ''; try { cwd = fs.readlinkSync(`${procDir}/${p}/cwd`); } catch { cwd = ''; }
+    // a pipeline process of THIS install: anything running its scripts or a run against it; my own shell is excluded above
+    if ((s.includes(inst) || cwd.startsWith(inst)) && /\b(node|bash|sh|python3?|claude)\b/.test(a[0] + ' ' + (a[1] || ''))) others.push(`${p} ${s.slice(0, 140)}`);
+  }
+  return res('alone', !others.length, others.length ? `${others.length} other process(es) are working against ${inst}: ${others.slice(0, 3).join(' | ')}` : `nothing else is working against ${inst}`, { others });
+}
+
+// ── 6. memory ────────────────────────────────────────────────────────────────────────────────────────────────────────
+function memory({ needMb, reserveMb = 3072, meminfo = '/proc/meminfo' }) {
+  const m = (fs.readFileSync(meminfo, 'utf8').match(/^MemAvailable:\s+(\d+) kB/m) || [])[1];
+  if (!m) return res('memory', false, `cannot read MemAvailable from ${meminfo}`);
+  const avail = Math.floor(Number(m) / 1024);
+  const ok = avail - reserveMb >= needMb;
+  return res('memory', ok, `${avail} MB available, ${reserveMb} MB kept for the host → ${avail - reserveMb} MB for the run; it needs ${needMb} MB`, { availMb: avail });
+}
+
+// ── 7. no-timeout ────────────────────────────────────────────────────────────────────────────────────────────────────
+// operator: no timeout may abort an agent. A leg time limit the launcher declares, or a `timeout` wrapper anywhere above
+// this process, is a clock that can cut an agent off mid-answer.
+function noTimeout({ legTimeoutSecs = 0, selfPid = process.pid, procDir = '/proc' }) {
+  const clocks = [];
+  if (Number(legTimeoutSecs) > 0) clocks.push(`the launcher declares a ${legTimeoutSecs}s leg time limit`);
+  for (const p of ancestors(selfPid, procDir)) { const a = cmdline(p, procDir); if (a.length && path.basename(a[0]) === 'timeout') clocks.push(`process ${p} runs under '${a.slice(0, 3).join(' ')}'`); }
+  return res('no-timeout', !clocks.length, clocks.length ? clocks.join('; ') : 'no time limit above the launch', { clocks });
+}
+
+// ── 8. checklist ─────────────────────────────────────────────────────────────────────────────────────────────────────
+// The operator's 12 items (2026-10-09). At pre-launch an item is GREEN or RED from what can be read now, or NOT-YET with
+// the phase that decides it; any RED stops the launch. "by design skipped" is not a state.
+function checklist({ env, results }) {
+  const by = Object.fromEntries(results.map((r) => [r.name, r]));
+  const man = env.EPAM_ESTIMATION_MANIFEST;
+  const it = (n, item, state, evidence) => ({ n, item, state, evidence });
+  const pf = by.preflight || {};
+  const items = [
+    it(1, 'Estimation manifest injected', !man ? 'RED' : (fs.existsSync(man) ? 'GREEN' : 'RED'), man ? `EPAM_ESTIMATION_MANIFEST=${man}${fs.existsSync(man) ? '' : ' (not found)'}` : 'EPAM_ESTIMATION_MANIFEST unset'),
+    it(2, 'Agent generation done agentically (reused roster in good order)', by.seed && by.cache ? (by.seed.ok && by.cache.ok ? 'GREEN' : 'RED') : 'NOT-YET', by.seed ? `${by.seed.detail}; ${by.cache ? by.cache.detail : ''}` : 'no seed to judge: decided at pause 1'),
+    it(3, 'Prompt generation done agentically (reused prompts in good order)', by.cache ? (by.cache.ok ? 'GREEN' : 'RED') : 'NOT-YET', by.cache ? by.cache.detail : 'decided at pause 1'),
+    it(4, 'Plan solid (checked against git facts)', 'NOT-YET', 'decided at pause 2 (plan of record)'),
+    it(5, 'Codelines correct', 'NOT-YET', 'decided at ingest (discovery + classification) and pause 1'),
+    it(6, 'Self-heal in place for ALL agents', pf.ok === false && /self-heal|routing/i.test(pf.detail || '') ? 'RED' : (pf.ok ? 'GREEN' : 'NOT-YET'), pf.ok ? 'pre-flight: self-heal observability routing passed' : (pf.detail || 'pre-flight not run')),
+    it(7, 'Ladder in place for ALL agents', pf.ok === false && /ladder|rung/i.test(pf.detail || '') ? 'RED' : (pf.ok ? 'GREEN' : 'NOT-YET'), pf.ok ? 'pre-flight: every assigned model is a rung of a declared ladder' : (pf.detail || 'pre-flight not run')),
+    it(8, 'Pause 1 and pause 2 working', env.EPAM_PAUSE_AFTER_AGENT_MINT === '1' && env.EPAM_PAUSE_BEFORE_WRITER === '1' ? 'GREEN' : 'RED', `EPAM_PAUSE_AFTER_AGENT_MINT=${env.EPAM_PAUSE_AFTER_AGENT_MINT || ''} EPAM_PAUSE_BEFORE_WRITER=${env.EPAM_PAUSE_BEFORE_WRITER || ''}`),
+    it(9, 'Cost collection and reporting working', by.cost ? (by.cost.ok ? 'GREEN' : 'RED') : 'NOT-YET', by.cost ? by.cost.detail : 'not checked'),
+    it(10, 'Worktrees up and working', 'NOT-YET', 'decided when the lanes open their worktrees'),
+    it(11, 'Langfuse cassette recording working', by.langfuse ? (by.langfuse.ok ? 'GREEN' : 'RED') : 'NOT-YET', by.langfuse ? by.langfuse.detail : 'not checked'),
+    it(12, 'Dashboards up, controlled by eleventy', pf.ok === false && /dashboard/i.test(pf.detail || '') ? 'RED' : (pf.ok ? 'GREEN' : 'NOT-YET'), pf.ok ? 'pre-flight: dashboard is up' : (pf.detail || 'pre-flight not run')),
+  ];
+  const red = items.filter((i) => i.state === 'RED');
+  return res('checklist', !red.length, `${items.filter((i) => i.state === 'GREEN').length} green, ${red.length} red, ${items.filter((i) => i.state === 'NOT-YET').length} not yet${red.length ? ` — red: ${red.map((i) => i.n).join(', ')}` : ''}`, { items });
+}
+
+/** The whole pre-launch, in order; every check runs (a report lists every red at once), the verdict is all-green. */
+function prelaunch(o) {
+  const results = [];
+  if (o.preflight !== false) results.push(preflight(o));
+  results.push(langfuse({ install: o.install, env: o.env, runId: o.runId, outDir: o.outDir }));
+  if (o.ticket) results.push(seed({ install: o.install, project: o.project, ticket: o.ticket, runsRoots: o.runsRoots || [] }));
+  if (o.codeline) results.push(cache({ install: o.install, project: o.project, codeline: o.codeline }));
+  results.push(cost({ install: o.install, set: o.set || o.env.EPAM_PROVIDER_SET || 'claude', tmpDir: o.outDir }));
+  results.push(alone({ install: o.install }));
+  results.push(memory({ needMb: Number(o.needMb || 4096) }));
+  results.push(noTimeout({ legTimeoutSecs: o.legTimeoutSecs || 0 }));
+  results.push(checklist({ env: o.env, results }));
+  const report = { at: new Date().toISOString(), runId: o.runId, install: o.install, project: o.project, ticket: o.ticket || null,
+    ok: results.every((r) => r.ok), results: results.map(({ log, ...r }) => r) };
+  if (o.outDir) { fs.mkdirSync(o.outDir, { recursive: true }); fs.writeFileSync(path.join(o.outDir, 'prelaunch.json'), `${JSON.stringify(report, null, 2)}\n`);
+    const pf = results.find((r) => r.name === 'preflight'); if (pf && pf.log) fs.writeFileSync(path.join(o.outDir, 'prelaunch-preflight.log'), pf.log); }
+  return report;
+}
+
+module.exports = { prelaunch, prelaunchCli, preflight, langfuse, langfuseEnv, seed, cache, cost, ladderModels, alone, memory, noTimeout, checklist, ancestors };
+
+/**
+ * THE COMMAND, for every pipeline:
+ *   prelaunch.js --install <i> --project <p> --run-id <id> --out <dir> [--ticket <KEY> --runs <runs dir>[,…]]
+ *                [--codeline <cl>] [--set <provider set>] [--need-mb <n>] [--leg-timeout-secs <s>] [--runner <launcher>]
+ *                [--prd <file>] [--preflight no]
+ * Prints each check and the verdict; writes <out>/prelaunch.json; exit 0 all green, 1 any red, 64 usage.
+ */
+function prelaunchCli(argv, env = process.env) {
+  const a = {}; for (let i = 0; i < argv.length; i += 2) a[argv[i].replace(/^--/, '')] = argv[i + 1];
+  for (const k of ['install', 'project', 'run-id', 'out']) if (!a[k]) { process.stderr.write(`prelaunch: --${k} is required\n`); return 64; }
+  const r = prelaunch({ install: path.resolve(a.install), project: a.project, runId: a['run-id'], outDir: path.resolve(a.out), env,
+    ticket: a.ticket, runsRoots: a.runs ? a.runs.split(',').map((d) => path.resolve(d)) : [], codeline: a.codeline,
+    set: a.set, needMb: a['need-mb'], legTimeoutSecs: a['leg-timeout-secs'], runner: a.runner, prd: a.prd, preflight: a.preflight !== 'no' });
+  process.stdout.write('── Pre-launch (amsd-pipeline-shared) ─────────────────────────────────────────\n');
+  for (const c of r.results) process.stdout.write(`  ${c.ok ? '✓' : '✗'} ${c.name}: ${c.detail}\n`);
+  const cl = r.results.find((c) => c.name === 'checklist');
+  if (cl) for (const it of cl.items) process.stdout.write(`      ${String(it.n).padStart(2)}. ${it.state.padEnd(7)} ${it.item} — ${it.evidence}\n`);
+  process.stdout.write(r.ok ? `  PRE-LAUNCH GREEN — ${path.join(a.out, 'prelaunch.json')}\n` : `  ✗ PRE-LAUNCH RED — the launch stops before any model call (${path.join(a.out, 'prelaunch.json')})\n`);
+  return r.ok ? 0 : 1;
+}
+if (require.main === module) process.exit(prelaunchCli(process.argv.slice(2)));