session-orchestrator 3.17.0 → 3.19.0

package/scripts/lib/state-md/mission-status.mjs

@@ -76,6 +76,46 @@ export function writeMissionStatus(contents, missionStatusArray) {
   return updateFrontmatterFields(contents, { 'mission-status': missionStatusArray.slice() });
 }
 
+/**
+ * Mirrors `status` onto the frontmatter `mission-status` entry whose `id` matches
+ * `taskId`, returning a NEW frontmatter object (copy-on-write at object, array and
+ * entry level — the input is never mutated, which keeps `parseMissionStatus`'s
+ * shallow-copy contract intact for anything else holding the same nested entries).
+ *
+ * UPDATE-ONLY by design: when the key is absent, is not an array, or holds no entry
+ * with a matching `id`, the frontmatter is returned unchanged. It is deliberately
+ * neither created nor an error, because `setMissionStatus(contents, taskId, status)`
+ * knows only `id` and `status` — it lacks the `task` and `wave` fields that
+ * `validateMissionStatusEntry` (mission-status-schema.mjs) requires, so a synthesised
+ * entry would be schema-invalid yet look authoritative to frontmatter consumers such
+ * as `vault-status/narrative-mirror.mjs`. Throwing is likewise excluded by the
+ * never-throw contract of `setMissionStatus`.
+ *
+ * `status` is mirrored verbatim without an enum check on purpose: gating it would
+ * reintroduce the exact divergence (body says X, frontmatter says Y) this sync exists
+ * to remove. An out-of-enum value now lands on BOTH surfaces, where the repo's own
+ * validator can see it.
+ *
+ * @param {object} frontmatter
+ * @param {string} taskId
+ * @param {string} status
+ * @returns {object}
+ */
+function syncFrontmatterMissionStatus(frontmatter, taskId, status) {
+  if (frontmatter === null || typeof frontmatter !== 'object' || Array.isArray(frontmatter)) {
+    return frontmatter;
+  }
+  const raw = frontmatter['mission-status'];
+  if (!Array.isArray(raw)) return frontmatter;
+  const idx = raw.findIndex(
+    (e) => e !== null && typeof e === 'object' && !Array.isArray(e) && e.id === taskId
+  );
+  if (idx === -1) return frontmatter;
+  const entries = raw.slice();
+  entries[idx] = { ...raw[idx], status };
+  return { ...frontmatter, 'mission-status': entries };
+}
+
 /**
  * Sets (or updates) the mission status for a single task in the `## Mission Status` body
  * section of STATE.md. Creates the section if it does not exist.
@@ -83,6 +123,13 @@ export function writeMissionStatus(contents, missionStatusArray) {
  * Format of each entry in the section:
  *   - <taskId>: <status> (updated <ISO timestamp>)
  *
+ * Also mirrors `status` into the frontmatter `mission-status` entry with the same `id`
+ * (issue #960 — one writer, two sinks). The body section is what the coordinator writes
+ * during a wave; the frontmatter array is what `parseMissionStatus` consumers read
+ * (`vault-status/narrative-mirror.mjs`, session-end Phase 1.9/1.10). Before this sync the
+ * live writer and the reader sat on different surfaces and drifted apart in both
+ * directions. Frontmatter mirroring is UPDATE-ONLY — see `syncFrontmatterMissionStatus`.
+ *
  * Pure function — no I/O. Returns original `contents` unchanged on bad input.
  *
  * @param {string} contents - Current STATE.md file contents (string)
@@ -97,6 +144,9 @@ export function setMissionStatus(contents, taskId, status) {
   const parsed = parseStateMd(contents);
   if (parsed === null) return contents;
 
+  // Computed once so every return path below emits the same synced frontmatter.
+  const frontmatter = syncFrontmatterMissionStatus(parsed.frontmatter, taskId, status);
+
   const timestamp = new Date().toISOString();
   const bullet = `- ${taskId}: ${status} (updated ${timestamp})`;
   const lines = parsed.body.split('\n');
@@ -115,7 +165,7 @@ export function setMissionStatus(contents, taskId, status) {
     let bodyOut = parsed.body;
     if (!bodyOut.endsWith('\n')) bodyOut += '\n';
     bodyOut += `\n## Mission Status\n\n${bullet}\n`;
-    return serializeStateMd({ frontmatter: parsed.frontmatter, body: bodyOut });
+    return serializeStateMd({ frontmatter, body: bodyOut });
   }
 
   // Find end of section: next ## heading or end of lines
@@ -155,11 +205,11 @@ export function setMissionStatus(contents, taskId, status) {
       const before = lines.slice(0, headingIdx + 1);
       const after = lines.slice(insertAt);
       const rebuilt = [...before, '', bullet, ...after];
-      return serializeStateMd({ frontmatter: parsed.frontmatter, body: rebuilt.join('\n') });
+      return serializeStateMd({ frontmatter, body: rebuilt.join('\n') });
     }
   }
 
-  return serializeStateMd({ frontmatter: parsed.frontmatter, body: lines.join('\n') });
+  return serializeStateMd({ frontmatter, body: lines.join('\n') });
 }
 
 /**

package/scripts/lib/subagents-schema.mjs

@@ -14,7 +14,20 @@
  *   schema_version    1 (integer)
  *
  * Required for event='stop':
- *   duration_ms       positive integer — wall-clock time from start to stop
+ *   duration_ms       positive integer | null — wall-clock time from start to stop.
+ *                     null means "unknown": the producer could not recover a
+ *                     matching 'start' record to measure against (#917). null is
+ *                     an honest absence and is NOT interchangeable with 0.
+ *
+ * duration_ms provenance (#917) — why the write path and the read path differ:
+ *   Before #917 the producer defaulted duration_ms to 0 whenever the harness
+ *   omitted it, which it always does. Every stop record written up to that point
+ *   therefore carries a fabricated 0 (measured 2026-07-30: 2770 of 2770 stop
+ *   records in .orchestrator/metrics/subagents.jsonl). Those records still have
+ *   to read and migrate cleanly, so validation is lenient BY DEFAULT and accepts
+ *   0. Callers on the WRITE path opt into `{ strictDuration: true }`, which
+ *   rejects 0 outright — appendSubagent() does this, so no new record can
+ *   reintroduce the fabricated zero.
  *
  * Optional:
  *   agent_type        string | null — e.g. 'explore', 'writer', 'test-writer'
@@ -70,14 +83,21 @@ export class ValidationError extends Error {
  * violation. Does NOT mutate the input.
  *
  * Required fields: timestamp, event, agent_id, schema_version.
- * Additional requirement when event='stop': duration_ms (positive integer).
+ * Additional requirement when event='stop': duration_ms (integer or null).
  * Optional: agent_type, parent_session_id, token_input, token_output.
  *
  * @param {object} entry
+ * @param {object} [options]
+ * @param {boolean} [options.strictDuration=false] — when true, a stop record's
+ *   duration_ms must be a POSITIVE integer or null; 0 is rejected. Write-path
+ *   callers set this; readers/migrations leave it false so the pre-#917 corpus
+ *   (every stop record carrying a fabricated 0) still validates. See the module
+ *   header § duration_ms provenance.
  * @returns {object} the entry (unchanged) — validation is side-effect-free
  * @throws {ValidationError}
  */
-export function validateSubagent(entry) {
+export function validateSubagent(entry, options = {}) {
+  const strictDuration = options?.strictDuration === true;
   if (!entry || typeof entry !== 'object') {
     throw new ValidationError('subagent record must be a non-null object');
   }
@@ -114,15 +134,24 @@ export function validateSubagent(entry) {
     throw new ValidationError('agent_id must be a non-empty string', 'agent_id');
   }
 
-  // duration_ms — required for stop events
-  if (entry.event === 'stop') {
+  // duration_ms — required for stop events.
+  //
+  // null is an explicit, honest "duration unknown" (#917) — the producer found no
+  // matching 'start' record to measure against. It is deliberately distinct from
+  // 0, which under strictDuration is rejected as the signature of the pre-#917
+  // fabricated default. `undefined` still throws in BOTH modes: a stop record
+  // that omits the field entirely is a producer bug, not an unknown duration.
+  if (entry.event === 'stop' && entry.duration_ms !== null) {
+    const floor = strictDuration ? 1 : 0;
     if (
       typeof entry.duration_ms !== 'number' ||
       !Number.isInteger(entry.duration_ms) ||
-      entry.duration_ms < 0
+      entry.duration_ms < floor
     ) {
       throw new ValidationError(
-        'duration_ms must be a non-negative integer when event=stop',
+        strictDuration
+          ? 'duration_ms must be a positive integer or null when event=stop (0 is not a measurement)'
+          : 'duration_ms must be a non-negative integer or null when event=stop',
         'duration_ms',
       );
     }
@@ -252,11 +281,16 @@ export function migrateLegacySubagent(entry) {
  * Steps:
  *   1. Stamp schema_version if missing.
  *   2. Normalize (apply optional-field defaults).
- *   3. Validate — throws ValidationError on bad input.
+ *   3. Validate with strictDuration — throws ValidationError on bad input.
  *   4. Serialize to JSON + newline.
  *   5. mkdir(dirname, recursive: true).
  *   6. appendFile (POSIX append ≤ PIPE_BUF is atomic for typical JSONL lines).
  *
+ * This is the WRITE path, so it validates with `{ strictDuration: true }`: a stop
+ * record may carry a positive duration or an explicit null, never 0 (#917). The
+ * historic corpus is unaffected — it is only ever read, and readers/migrations use
+ * the lenient default. See the module header § duration_ms provenance.
+ *
  * @param {string} filePath — absolute path to target .jsonl file
  * @param {object} entry — candidate subagent record
  * @returns {Promise<object>} the validated + normalized entry that was written
@@ -268,7 +302,7 @@ export async function appendSubagent(filePath, entry) {
     schema_version: entry?.schema_version ?? CURRENT_SCHEMA_VERSION,
   };
   const normalized = normalizeSubagent(stamped);
-  const validated = validateSubagent(normalized);
+  const validated = validateSubagent(normalized, { strictDuration: true });
   const line = JSON.stringify(validated) + '\n';
   await mkdir(path.dirname(filePath), { recursive: true });
   await appendFile(filePath, line, 'utf8');

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

@@ -38,6 +38,7 @@
 import { execFile as execFileCb } from 'node:child_process';
 import { promisify } from 'node:util';
 import { fingerprintFinding } from './fingerprint.mjs';
+import { resolveRepoSpec } from '../vcs-repo-spec.mjs';
 
 const realExecFile = promisify(execFileCb);
 
@@ -293,6 +294,9 @@ function levenshtein(a, b) {
  * @param {Set<string>} opts.existingFingerprints - fingerprints of issues already filed
  * @param {boolean} [opts.dryRun] - if true, return command without spawning
  * @param {Function} [opts.execFile] - DI seam for testing; defaults to node:child_process execFile
+ * @param {string} [opts.project] - GitLab project path (passed via --repo if provided; #872: otherwise auto-detected)
+ * @param {string} [opts.repoRoot=process.cwd()] - cwd passed to resolveRepoSpecFn for remote auto-detection
+ * @param {(o: { repoRoot: string, vcs: 'gitlab' }) => string|undefined} [opts.resolveRepoSpecFn] - injectable `--repo` auto-detector; defaults to the real `resolveRepoSpec`
  * @returns {Promise<{action: 'create'|'noop', iid?: number, command?: string[]}>}
  */
 export async function reconcileFinding({
@@ -300,6 +304,9 @@ export async function reconcileFinding({
   existingFingerprints,
   dryRun = false,
   execFile: execFileOpt,
+  project,
+  repoRoot = process.cwd(),
+  resolveRepoSpecFn = resolveRepoSpec,
 }) {
   // Resolve execFile — DI seam for tests; never caller-supplied binary path (ADR-364 §C5 HIGH fix).
   const execFileFn = typeof execFileOpt === 'function' ? execFileOpt : realExecFile;
@@ -354,6 +361,18 @@ export async function reconcileFinding({
     body,
   ];
 
+  // #872: explicit project always wins; otherwise auto-detect a --repo spec
+  // from the local git remotes (host-pinning — a bare glab spawn falls back
+  // to the ambient GITLAB_HOST, which can silently target the wrong
+  // instance on a multi-instance host).
+  const effectiveProject = project ?? resolveRepoSpecFn({ repoRoot, vcs: 'gitlab' });
+  if (effectiveProject !== undefined) {
+    if (ARG_BOUNDARY_DANGEROUS.test(effectiveProject)) {
+      throw new ReconcileError('project contains forbidden characters', 'VALIDATION');
+    }
+    cmd.push('--repo', effectiveProject);
+  }
+
   if (dryRun) {
     return { action: 'create', command: cmd };
   }
@@ -385,10 +404,12 @@ export async function reconcileFinding({
  * fingerprints from issue bodies for downstream dedup.
  *
  * @param {object} [opts]
- * @param {string} [opts.project] - GitLab project path (passed via --repo if provided)
+ * @param {string} [opts.project] - GitLab project path (passed via --repo if provided; #872: otherwise auto-detected)
  * @param {string} [opts.label='from:test-runner'] - label filter for the query
  * @param {number} [opts.maxBuffer=4194304] - maxBuffer for execFile (4 MB default, #389)
  * @param {Function} [opts.execFile] - DI seam for testing; defaults to node:child_process execFile
+ * @param {string} [opts.repoRoot=process.cwd()] - cwd passed to resolveRepoSpecFn for remote auto-detection
+ * @param {(o: { repoRoot: string, vcs: 'gitlab' }) => string|undefined} [opts.resolveRepoSpecFn] - injectable `--repo` auto-detector; defaults to the real `resolveRepoSpec`
  * @returns {Promise<
  *   {ok: true, issues: Array<{iid: number, title: string, body: string}>, fingerprints: Set<string>}
  *   | {ok: false, error: {code: string, message: string}}
@@ -399,6 +420,8 @@ export async function listExistingFindings({
   label = 'from:test-runner',
   maxBuffer = DEFAULT_MAX_BUFFER,
   execFile: execFileOpt,
+  repoRoot = process.cwd(),
+  resolveRepoSpecFn = resolveRepoSpec,
 } = {}) {
   // Binary is always the allowlisted value — never caller-supplied (ADR-364 §C5 HIGH fix).
   const bin = RECONCILE_ALLOWLISTED_BINS.glab;
@@ -414,15 +437,18 @@ export async function listExistingFindings({
 
   const args = ['issue', 'list', '--label', label, '--output', 'json'];
 
-  // Optionally scope to a specific project (--repo flag)
-  if (project !== undefined) {
-    if (ARG_BOUNDARY_DANGEROUS.test(project)) {
+  // Optionally scope to a specific project (--repo flag). #872: explicit
+  // project always wins; otherwise auto-detect a --repo spec from the local
+  // git remotes (host-pinning).
+  const effectiveProject = project ?? resolveRepoSpecFn({ repoRoot, vcs: 'gitlab' });
+  if (effectiveProject !== undefined) {
+    if (ARG_BOUNDARY_DANGEROUS.test(effectiveProject)) {
       return {
         ok: false,
         error: { code: 'VALIDATION', message: 'project contains forbidden characters' },
       };
     }
-    args.push('--repo', project);
+    args.push('--repo', effectiveProject);
   }
 
   let stdout;
@@ -501,7 +527,7 @@ export async function listExistingFindings({
  * Create a new finding as a GitLab issue.
  *
  * @param {object} opts
- * @param {string} [opts.project] - GitLab project path (--repo)
+ * @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.title - issue title (no [Test] prefix added here — caller decides)
  * @param {string} opts.body - issue description body; must not exceed 65536 bytes (#389)
@@ -509,6 +535,8 @@ export async function listExistingFindings({
  * @param {boolean} [opts.dryRun=false] - if true, return command without spawning
  * @param {number} [opts.maxBuffer=4194304] - maxBuffer for execFile (4 MB, #389)
  * @param {Function} [opts.execFile] - DI seam for testing; defaults to node:child_process execFile
+ * @param {string} [opts.repoRoot=process.cwd()] - cwd passed to resolveRepoSpecFn for remote auto-detection
+ * @param {(o: { repoRoot: string, vcs: 'gitlab' }) => string|undefined} [opts.resolveRepoSpecFn] - injectable `--repo` auto-detector; defaults to the real `resolveRepoSpec`
  * @returns {Promise<
  *   {ok: true, action: 'create', iid?: number, command?: string[]}
  *   | {ok: false, error: {code: string, message: string}}
@@ -523,6 +551,8 @@ export async function createFinding({
   dryRun = false,
   maxBuffer = DEFAULT_MAX_BUFFER,
   execFile: execFileOpt,
+  repoRoot = process.cwd(),
+  resolveRepoSpecFn = resolveRepoSpec,
 }) {
   // --- Input validation ---
   if (typeof title !== 'string' || title.length === 0) {
@@ -562,14 +592,17 @@ export async function createFinding({
 
   const args = ['issue', 'create', '--title', title, '--label', labels, '--description', body];
 
-  if (project !== undefined) {
-    if (ARG_BOUNDARY_DANGEROUS.test(project)) {
+  // #872: explicit project always wins; otherwise auto-detect a --repo spec
+  // from the local git remotes (host-pinning).
+  const effectiveProject = project ?? resolveRepoSpecFn({ repoRoot, vcs: 'gitlab' });
+  if (effectiveProject !== undefined) {
+    if (ARG_BOUNDARY_DANGEROUS.test(effectiveProject)) {
       return {
         ok: false,
         error: { code: 'VALIDATION', message: 'project contains forbidden characters' },
       };
     }
-    args.push('--repo', project);
+    args.push('--repo', effectiveProject);
   }
 
   if (dryRun) {
@@ -616,12 +649,14 @@ export async function createFinding({
  * Add a comment to an existing finding issue.
  *
  * @param {object} opts
- * @param {string} [opts.project] - GitLab project path (--repo)
+ * @param {string} [opts.project] - GitLab project path (--repo; #872: otherwise auto-detected)
  * @param {number} opts.iid - issue IID to comment on
  * @param {string} opts.comment - comment body; must not exceed 65536 bytes (#389)
  * @param {boolean} [opts.dryRun=false] - if true, return command without spawning
  * @param {number} [opts.maxBuffer=4194304] - maxBuffer for execFile (4 MB, #389)
  * @param {Function} [opts.execFile] - DI seam for testing; defaults to node:child_process execFile
+ * @param {string} [opts.repoRoot=process.cwd()] - cwd passed to resolveRepoSpecFn for remote auto-detection
+ * @param {(o: { repoRoot: string, vcs: 'gitlab' }) => string|undefined} [opts.resolveRepoSpecFn] - injectable `--repo` auto-detector; defaults to the real `resolveRepoSpec`
  * @returns {Promise<
  *   {ok: true, action: 'comment', command?: string[]}
  *   | {ok: false, error: {code: string, message: string}}
@@ -634,6 +669,8 @@ export async function updateFinding({
   dryRun = false,
   maxBuffer = DEFAULT_MAX_BUFFER,
   execFile: execFileOpt,
+  repoRoot = process.cwd(),
+  resolveRepoSpecFn = resolveRepoSpec,
 }) {
   // --- Input validation ---
   if (!Number.isInteger(iid) || iid < 1) {
@@ -657,14 +694,17 @@ export async function updateFinding({
   // iid is a number — safe to convert to string; no arg-boundary concerns
   const args = ['issue', 'note', String(iid), '--message', comment];
 
-  if (project !== undefined) {
-    if (ARG_BOUNDARY_DANGEROUS.test(project)) {
+  // #872: explicit project always wins; otherwise auto-detect a --repo spec
+  // from the local git remotes (host-pinning).
+  const effectiveProject = project ?? resolveRepoSpecFn({ repoRoot, vcs: 'gitlab' });
+  if (effectiveProject !== undefined) {
+    if (ARG_BOUNDARY_DANGEROUS.test(effectiveProject)) {
       return {
         ok: false,
         error: { code: 'VALIDATION', message: 'project contains forbidden characters' },
       };
     }
-    args.push('--repo', project);
+    args.push('--repo', effectiveProject);
   }
 
   if (dryRun) {