session-orchestrator 4.1.0 → 5.0.0

package/scripts/lib/test-runner/artifact-paths.mjs

@@ -4,6 +4,8 @@
  * All functions are side-effect free. Callers are responsible for mkdir.
  *
  * Exports:
+ *   RUN_ID_PATTERN               → RegExp  accepted run-id shape
+ *   assertRunId(runId)           → string  the runId, or throws TypeError
  *   makeRunId()                  → string  e.g., '12345-1715688000123'
  *   runDirPath(runId)            → string
  *   findingsPath(runId)          → string
@@ -19,6 +21,30 @@ import path from 'node:path';
 const ROLLUP_REL = '.orchestrator/metrics/test-runs.jsonl';
 const TEST_RUNS_REL = '.orchestrator/metrics/test-runs';
 
+/**
+ * Accepted shape of a run id — the single definition for test-runner AND
+ * ux-grill (`scripts/lib/ux-grill/paths.mjs` imports it; ux-grill → test-runner
+ * is the allowed dependency direction). A run id reaches `path.join` unescaped,
+ * so `/` would escape the run directory. `.` and `..` match this class too and
+ * are rejected separately by {@link assertRunId}.
+ * @type {RegExp}
+ */
+export const RUN_ID_PATTERN = /^[A-Za-z0-9._-]+$/;
+
+/**
+ * Validate a run id: a string matching {@link RUN_ID_PATTERN} that is not `.`
+ * or `..` (both resolve to the base dir or its parent — path traversal, #1330).
+ * @param {unknown} runId
+ * @returns {string} the same runId
+ * @throws {TypeError} if runId is not a string, does not match the pattern, or is `.`/`..`
+ */
+export function assertRunId(runId) {
+  if (typeof runId !== 'string' || !RUN_ID_PATTERN.test(runId) || runId === '.' || runId === '..') {
+    throw new TypeError(`runId must match ${RUN_ID_PATTERN} and not be "." or "..", got ${JSON.stringify(runId)}`);
+  }
+  return runId;
+}
+
 /**
  * Generate a unique run-id from PID + millisecond timestamp.
  * Format: `${process.pid}-${Date.now()}`
@@ -29,15 +55,14 @@ export function makeRunId() {
 }
 
 /**
- * Construct the run-dir path for a given runId.
+ * Construct the run-dir path for a given runId. Every other per-run builder in
+ * this module routes through here, so this is the single path-traversal guard.
  * @param {string} runId
  * @returns {string}
+ * @throws {TypeError} on an invalid runId (see {@link assertRunId})
  */
 export function runDirPath(runId) {
-  if (typeof runId !== 'string' || runId.length === 0) {
-    throw new TypeError('runDirPath: runId must be a non-empty string');
-  }
-  return path.join(TEST_RUNS_REL, runId);
+  return path.join(TEST_RUNS_REL, assertRunId(runId));
 }
 
 /**

package/scripts/lib/test-runner/issue-reconcile.mjs

@@ -148,6 +148,21 @@ function sanitizeRecommendation(text) {
   return text.replace(/\*\*Fingerprint:\*\*/gi, '__Fingerprint__');
 }
 
+/**
+ * Render untrusted text as the content of ONE inline Markdown code span:
+ * sentinel literals neutralised (sanitizeRecommendation), line breaks and NUL
+ * folded to a space, backticks turned into `'` — so a page-controlled locator
+ * can neither close its code span nor start a new body line.
+ *
+ * @param {unknown} text
+ * @returns {string}
+ */
+function codeSpanContent(text) {
+  return sanitizeRecommendation(String(text ?? ''))
+    .replace(/[\r\n\0]+/g, ' ')
+    .replace(/`/g, "'");
+}
+
 // ---------------------------------------------------------------------------
 // Body-length validation (#389 SEC-IR-LOW-1)
 // ---------------------------------------------------------------------------
@@ -182,25 +197,31 @@ function checkBodyLength(body) {
  * Newlines within the body are intentional and safe — execFile passes
  * --description as a single argv element, not through a shell.
  *
- * Applies sanitizeRecommendation() to the recommendation field (#388) before
- * embedding it, so the authoritative `**Fingerprint:** \`<fp>\`` sentinel
- * line cannot be spoofed by attacker-controlled recommendation text.
+ * Every free-text field is sanitised before embedding, so the authoritative
+ * `**Fingerprint:** \`<fp>\`` sentinel cannot be spoofed: `recommendation`
+ * (#388) and `description` go through sanitizeRecommendation() — description
+ * is line 1, BEFORE the real sentinel, and carries verbatim page HTML (axe
+ * results), while the extractor takes the FIRST match. `locator` goes through
+ * codeSpanContent() so it also cannot break out of its code span.
+ *
+ * Exported (#1331) so direct `createFinding` callers can build a body that
+ * passes its sentinel check instead of hand-writing the sentinel line.
  *
  * @param {object} finding
  * @param {string} fp - 16-char hex fingerprint
  * @returns {string}
  */
-function buildIssueBody(finding, fp) {
+export function buildIssueBody(finding, fp) {
   const safeRecommendation = sanitizeRecommendation(finding.recommendation);
   const lines = [
-    finding.description,
+    sanitizeRecommendation(finding.description),
     '',
     safeRecommendation ? `**Recommendation:** ${safeRecommendation}` : null,
     '',
     `**Fingerprint:** \`${fp}\``,
     `**Severity:** ${finding.severity}`,
     `**Check:** ${finding.checkId}`,
-    `**Locator:** \`${finding.locator}\``,
+    `**Locator:** \`${codeSpanContent(finding.locator)}\``,
   ];
   return lines.filter((line) => line !== null).join('\n');
 }
@@ -528,9 +549,12 @@ export async function listExistingFindings({
  *
  * @param {object} opts
  * @param {string} [opts.project] - GitLab project path (--repo; #872: otherwise auto-detected)
- * @param {string} opts.fingerprint - 16-hex fingerprint (appended as sentinel)
+ * @param {string} opts.fingerprint - 16-hex fingerprint; NOT appended here — `body` must already carry it
  * @param {string} opts.title - issue title (no [Test] prefix added here — caller decides)
- * @param {string} opts.body - issue description body; must not exceed 65536 bytes (#389)
+ * @param {string} opts.body - issue description body; must not exceed 65536 bytes (#389) and must
+ *   carry the `**Fingerprint:** \`<fingerprint>\`` sentinel for this same fingerprint (#1331) —
+ *   build it with {@link buildIssueBody}
+
  * @param {string} [opts.labels='from:test-runner'] - comma-separated label string
  * @param {boolean} [opts.dryRun=false] - if true, return command without spawning
  * @param {number} [opts.maxBuffer=4194304] - maxBuffer for execFile (4 MB, #389)
@@ -590,6 +614,19 @@ export async function createFinding({
   const bodyLengthError = checkBodyLength(body);
   if (bodyLengthError) return bodyLengthError;
 
+  // #1331: dedup reads the fingerprint back out of the body on the next run, and
+  // nothing here appends it. A body without the matching sentinel would file an
+  // issue no later run can recognise — every run would then open a duplicate.
+  if (extractFingerprintFromBody(body) !== fingerprint) {
+    return {
+      ok: false,
+      error: {
+        code: 'VALIDATION',
+        message: 'body must carry a **Fingerprint:** sentinel matching fingerprint (use buildIssueBody)',
+      },
+    };
+  }
+
   const args = ['issue', 'create', '--title', title, '--label', labels, '--description', body];
 
   // #872: explicit project always wins; otherwise auto-detect a --repo spec

package/scripts/lib/tmux-layout/layouts.mjs

@@ -11,7 +11,8 @@
  *   Pane 3 (bottom-right) — vcs-aware CI watch (poll-loop from detectVcsCommand)
  *   Pane 4 (bottom-left)  — tail -F .orchestrator/metrics/events.jsonl | jq select(wave|gate|spiral)
  *   Pane 5 (optional)     — agent-status telemetry (#565), only when withStatusPane is true:
- *                           poll-loop over .orchestrator/runtime/agent-status-current.json
+ *                           poll-loop over readCurrentStatus() from scripts/lib/agent-status.mjs,
+ *                           which reports provenance (live-map / rebuilt-log / stale-cache) — #1342.
  *
  * Debug layout pane map (user-facing numbering):
  *   Pane 1 (top-left)     — scratch shell (NO command — default tmux shell, AUQ-001 compliance)
@@ -58,6 +59,61 @@ function shellQuote(s) {
   return "'" + String(s).replace(/'/g, "'\\''") + "'";
 }
 
+/** Poll interval (seconds) of the agent-status pane loop. */
+const STATUS_PANE_POLL_SECONDS = 2;
+
+/**
+ * Build the ONE-SHOT render command of the agent-status pane (#1342).
+ *
+ * The pane used to `jq` `.orchestrator/runtime/agent-status-current.json` directly.
+ * That file is a REBUILDABLE CACHE, not the source of truth: after a lock timeout
+ * (or a death between the ledger append and the map write) it shows `running` for
+ * an agent whose ledger already says `completed`. So the pane now goes through
+ * `readCurrentStatus()` — the only reader that folds the ledger tail and reports
+ * PROVENANCE — and prints that provenance in its header line:
+ *
+ *   agent-status · source=<live-map|rebuilt-log|stale-cache|absent> · at=<ISO|n/a>[ · STALE][ · DEGRADED: <reasons>]
+ *
+ * A `stale-cache` source or any `degraded` reason is marked in TEXT (leading `⚠`
+ * plus the words STALE / DEGRADED), never by colour alone. `absent` (nothing on
+ * disk yet) stays UNMARKED — a fresh repo is not a degradation (HR-101).
+ *
+ * Exported so a consumer test can run the render ONCE instead of the poll loop.
+ *
+ * Shell-shape notes (both load-bearing):
+ *   - the `-e` script is wrapped in SINGLE quotes, so the JS below uses only
+ *     double-quoted strings: inside single quotes no `$`, backtick or interactive
+ *     `!` history expansion can touch it.
+ *   - the module path is resolved from THIS file's own URL (never a hardcoded home
+ *     path), exactly as the sibling pane commands stay relative-to-cwd.
+ *
+ * @returns {string} a single shell command; prints the pane body once and exits.
+ */
+export function buildStatusPaneRenderCommand() {
+  // `%27` guard: a single quote in the repo path would otherwise end the shell
+  // single-quoted `-e` argument.
+  const moduleHref = new URL('../agent-status.mjs', import.meta.url).href.replace(/'/g, '%27');
+  const js = [
+    `import {readCurrentStatus} from ${JSON.stringify(moduleHref)};`,
+    'const v=readCurrentStatus({repoRoot:process.cwd()});',
+    'const ids=Object.keys(v.entries).sort();',
+    // An EMPTY channel (no ledger yet, no cache yet) is the normal fresh-repo
+    // state, not a degradation — marking it would fire the warning on every
+    // session and teach the operator to ignore it (host-resources.md HR-101).
+    // `readCurrentStatus()` names that state `absent` and emits no `degraded`,
+    // so the unmarked case keys on the SOURCE, not on a reason allowlist.
+    'const bare=v.source==="absent";',
+    'const marks=[];',
+    'if(!bare&&v.source==="stale-cache")marks.push("STALE");',
+    'if(!bare&&v.degraded)marks.push("DEGRADED: "+v.degraded.reasons.join(","));',
+    'const head=(marks.length>0?"\u26a0 ":"")+"agent-status \u00b7 source="+v.source+" \u00b7 at="+(v.at||"n/a")+(marks.length>0?" \u00b7 "+marks.join(" \u00b7 "):"");',
+    'console.log(head);',
+    'if(ids.length===0)console.log("no agent-status yet \u2014 set persistence:true + run a wave (see skills/wave-executor/wave-loop.md \u00a7 3a-bis)");',
+    'for(const id of ids){const r=v.entries[id]||{};const what=typeof r.text==="string"?r.text:(r.step!==undefined?r.step+"/"+r.total+(r.label?" "+r.label:""):"unknown");console.log(id+"  "+what+"  "+(r.ts||"no-ts"));}',
+  ].join('');
+  return `node --input-type=module -e '${js}'`;
+}
+
 // ---------------------------------------------------------------------------
 // renderDefaultLayout
 // ---------------------------------------------------------------------------
@@ -91,9 +147,11 @@ async function _renderDefaultLayoutInner({ sessionName, force, projectRoot, vcsC
   const pane2Cmd = `tail -F ${stateMdPath}`;
   const pane3Cmd = vcs.command;
   const pane4Cmd = `tail -F .orchestrator/metrics/events.jsonl | jq --unbuffered 'select(.event | test("wave|gate|spiral"))'`;
-  // Pane 5 (optional, #565): poll the LWW agent-status map. The `|| echo` fallback
-  // (mirrors Pane 3 style) keeps a missing file / absent jq from erroring the pane.
-  const pane5Cmd = `while true; do clear; jq . .orchestrator/runtime/agent-status-current.json 2>/dev/null || echo 'no agent-status yet — set persistence:true + run a wave (see skills/wave-executor/wave-loop.md § 3a-bis)'; sleep 2; done`;
+  // Pane 5 (optional, #565 / #1342): poll `readCurrentStatus()` — NOT the cache
+  // file — so the pane can never present a stale `running` as live. The renderer
+  // prints its own "no agent-status yet" line when the channel is empty, and is
+  // exported (buildStatusPaneRenderCommand) so a test can run it once.
+  const pane5Cmd = `while true; do clear; ${buildStatusPaneRenderCommand()}; sleep ${STATUS_PANE_POLL_SECONDS}; done`;
 
   // 4. Session-collision check
   const collision = isSessionCollision(sessionName);