session-orchestrator 3.21.0 → 3.23.0

package/scripts/lib/vault-status/narrative-mirror.mjs

@@ -18,6 +18,7 @@
  *
  * Exports:
  *   GENERATOR_MARKER       — frontmatter sentinel identifying generator-owned files
+ *   NARRATIVE_EVENT        — canonical telemetry event name for a mirror attempt
  *   extractNarrative       — pure: STATE.md contents → { waveHistory, deviations, whatNotToRetry, missionStatus }
  *   renderNarrative        — pure: narrative + repo + now → full markdown (frontmatter + body)
  *   writeNarrative         — idempotent write with skip-handwritten / skip-noop / dry-run + _overview refusal
@@ -30,6 +31,7 @@ import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
 
+import { emitEvent, sessionAttribution } from '../events.mjs';
 import { parseStateMd, parseMissionStatus } from '../state-md.mjs';
 import {
   parseFrontmatter,
@@ -557,6 +559,128 @@ function resolveLooseSlug(vaultDir, candidateSlug, fsSeam = {}) {
   return matches.length === 1 ? matches[0] : candidateSlug;
 }
 
+// ── Telemetry ────────────────────────────────────────────────────────────────────
+
+/**
+ * Canonical event name for a narrative-mirror attempt (issue #1129).
+ *
+ * ONE event per {@link mirrorNarrative} call — the REJECTION and NO-OP paths
+ * included, because those are the point. Before this existed, a vault-disabled
+ * config, a missing STATE.md, a hand-authored target file and a healthy write
+ * were all indistinguishable from the ledger's side: measured 2026-08-23 over
+ * 28 387 records in `.orchestrator/metrics/events.jsonl`, ZERO board/mirror
+ * events, because this module did not import {@link emitEvent} at all. Its only
+ * caller is shell prose in `skills/session-end/session-metrics-write.md`, whose
+ * `mode: warn` degradation prints a WARNING and closes the session anyway — so
+ * an outage of this writer left no durable trace whatsoever.
+ *
+ * Name deliberately NOT minted here: it is the one the wave assigned, so the
+ * fact "a narrative mirror ran" has exactly one address in the ledger.
+ */
+export const NARRATIVE_EVENT = 'orchestrator.vault.narrative_mirrored';
+
+/**
+ * Emit the narrative-mirror telemetry record. Best-effort: never throws, never
+ * alters the mirror result.
+ *
+ * ABSENT IS NOT ZERO (`docs/events-schema.md`): every optional field is spread
+ * conditionally, so an UNMEASURED field is MISSING from the record rather than
+ * written as `0`. `chars: 0` would then honestly mean "the narrative rendered to
+ * an empty document"; an absent `chars` means "no render was reached on this
+ * path" — reading the missing key as `0` conflates the two in both directions.
+ *
+ * NAMED CEILING (build-value BV-004): when `repoRoot` is absent or empty this
+ * emits NOTHING. `emitEvent` without `opts.repoRoot` falls back to
+ * `SO_PROJECT_DIR` (#941), so the only destination left for a rootless call is
+ * whichever repo the process happens to sit in — i.e. a caller that named no
+ * repo would silently append to a FOREIGN ledger, and the two call shapes that
+ * reach this branch today are the `repoRoot: ''` / omitted-`repoRoot` unit
+ * tests, which would then write synthetic records into this repo's real fleet
+ * telemetry on every suite run. REVISIT TRIGGER: if a production caller ever
+ * legitimately invokes `mirrorNarrative` without a `repoRoot`, that call needs a
+ * destination decision of its own — not this silent skip.
+ *
+ * @param {object} opts
+ * @param {string} [opts.repoRoot] — pins the ledger to THIS repo's
+ *   `.orchestrator/metrics/events.jsonl` (#941), and supplies session attribution.
+ * @param {string} opts.action — the `action` the mirror returned, or `'error'`
+ *   when the writer threw. ALWAYS present.
+ * @param {string} [opts.path] — resolved narrative path, when one was resolved.
+ * @param {number} [opts.chars] — length of the rendered narrative document this
+ *   call produced. Present whenever the render was reached (so also on
+ *   `skipped-noop` / `dry-run`, where the document was built but not written —
+ *   `action` is what says whether it landed); absent on the earlier no-op paths,
+ *   which return before anything is rendered.
+ * @param {string} [opts.errorCode] — `err.code` on the throw path (a bounded
+ *   token such as `EACCES`). The error MESSAGE is deliberately NOT recorded: it
+ *   can quote a path or STATE.md content, and this module's whole reason for
+ *   masking (#1025) is that such prose carries secrets.
+ * @returns {Promise<void>}
+ */
+/**
+ * Reduce an absolute vault path to its LAST TWO segments for telemetry.
+ *
+ * The full path is the module's public return contract and stays untouched.
+ * What must not travel is the path in the EMITTED payload: on a real host it
+ * reads `/Users/<name>/Projects/<vault>/01-projects/<private-slug>/…`, i.e. an
+ * OS username plus a private project slug. Those are exactly the two shapes
+ * `scripts/lib/validate/check-owner-leakage.mjs` blocks as CP1 and CP6 — and
+ * that scanner structurally cannot see this one, because it walks `git ls-files`
+ * and `.orchestrator/metrics/*.jsonl` is gitignored (`.gitignore:40`).
+ * The record is invisible to the pre-commit guard and visible to the optional
+ * Clank webhook (`scripts/lib/events.mjs`, `CLANK_EVENT_URL`), which posts the
+ * payload verbatim with no redaction.
+ *
+ * The BASENAME is the deliberate ceiling — one segment, not two. Two segments
+ * would keep the parent directory, and under `01-projects/` that directory IS
+ * the private project slug, i.e. exactly the CP6 shape this is meant to drop.
+ * The diagnostic value lives in the filename alone: it says WHICH writer ran
+ * (`_session-narrative.md` vs `_active-sessions.md`), which is the question the
+ * event exists to answer. Which project it was is already answerable from the
+ * record's own `session_id` / repo-scoped ledger location.
+ * Revisit trigger: a consumer that needs more than the filename — then it
+ * belongs in the RETURN value, which already carries the absolute path, never
+ * in the event.
+ *
+ * @param {unknown} outputPath
+ * @returns {string|undefined} `undefined` when there is nothing measured to report.
+ */
+function telemetrySafePath(outputPath) {
+  if (typeof outputPath !== 'string' || outputPath.length === 0) return undefined;
+  const base = path.basename(outputPath);
+  return base.length > 0 ? base : undefined;
+}
+
+async function emitNarrativeEvent({ repoRoot, action, path: outputPath, chars, errorCode }) {
+  if (typeof repoRoot !== 'string' || repoRoot.length === 0) return;
+  try {
+    await emitEvent(
+      NARRATIVE_EVENT,
+      {
+        action,
+        ...(telemetrySafePath(outputPath) !== undefined ? { path_tail: telemetrySafePath(outputPath) } : {}),
+        // `typeof … === 'number'` rather than `!= null`: the repo's eslint
+        // `eqeqeq: always` forbids the loose form, and this shape additionally
+        // refuses a non-numeric `chars` outright. A measured `0` still lands.
+        ...(typeof chars === 'number' ? { chars } : {}),
+        // `typeof === 'string'`, not truthiness: an `err.code` of '' is a measured
+        // empty code, and the sibling `chars` field four lines up already states
+        // why this file rejects the loose form.
+        ...(typeof errorCode === 'string' && errorCode.length > 0 ? { error_code: errorCode } : {}),
+        // session_id / semantic_session_id — omitted entirely when no session
+        // lock is readable (CI, ad-hoc runs). See sessionAttribution's contract:
+        // a fabricated id would read as a real session.
+        ...sessionAttribution(repoRoot),
+      },
+      { repoRoot },
+    );
+  } catch {
+    /* Best-effort telemetry. emitEvent does real file I/O (mkdir + append), so a
+       read-only or occupied ledger path WILL throw — and a broken ledger must
+       never fail a narrative write. The mirror result is authoritative. */
+  }
+}
+
 // ── Convenience orchestration ────────────────────────────────────────────────────
 
 /**
@@ -594,10 +718,50 @@ function resolveLooseSlug(vaultDir, candidateSlug, fsSeam = {}) {
  * @returns {Promise<{ action: string, path?: string }>}
  */
 export async function mirrorNarrative(opts) {
+  let outcome;
+  try {
+    outcome = await runNarrativeMirror(opts);
+  } catch (err) {
+    // The harshest silent-failure case: `session-metrics-write.md` catches this
+    // throw, prints a WARNING under `mode: warn` and closes the session anyway.
+    // Record it, then re-throw — telemetry observes, it never swallows.
+    await emitNarrativeEvent({
+      repoRoot: opts?.repoRoot,
+      action: 'error',
+      errorCode: typeof err?.code === 'string' ? err.code : undefined,
+    });
+    throw err;
+  }
+
+  await emitNarrativeEvent({
+    repoRoot: opts?.repoRoot,
+    action: outcome.result.action,
+    path: outcome.result.path,
+    chars: outcome.chars,
+  });
+
+  return outcome.result;
+}
+
+/**
+ * The mirror itself — every early return of {@link mirrorNarrative} lives here.
+ *
+ * Split out so that exactly ONE emit site covers EVERY outcome: a future early
+ * return added inside this function is telemetered by construction, whereas
+ * hand-placing an emit beside each of the seven `return`s makes "forgot the new
+ * one" the default failure. The `chars` companion travels beside the result
+ * rather than inside it because the returned object is a PUBLIC shape that
+ * callers (and tests) compare with `toEqual` — adding a key there would be an
+ * observable contract change for a purely internal measurement.
+ *
+ * @param {Parameters<typeof mirrorNarrative>[0]} opts
+ * @returns {Promise<{ result: { action: string, path?: string }, chars?: number }>}
+ */
+async function runNarrativeMirror(opts) {
   const { repoRoot, repo, now = new Date(), dryRun = false, fs: injectedFs, hostPaths } = opts;
 
   if (typeof repoRoot !== 'string' || repoRoot.length === 0) {
-    return { action: 'skipped-vault-disabled' };
+    return { result: { action: 'skipped-vault-disabled' } };
   }
 
   // Read Session Config (CLAUDE.md / AGENTS.md) and resolve vault settings.
@@ -606,12 +770,12 @@ export async function mirrorNarrative(opts) {
     const configText = await readConfigFile(repoRoot);
     config = parseSessionConfig(configText, { hostPaths });
   } catch {
-    return { action: 'skipped-vault-disabled' };
+    return { result: { action: 'skipped-vault-disabled' } };
   }
 
   const vaultIntegration = config?.['vault-integration'];
   if (!vaultIntegration || vaultIntegration.enabled !== true) {
-    return { action: 'skipped-vault-disabled' };
+    return { result: { action: 'skipped-vault-disabled' } };
   }
 
   // Defense-in-depth: when the caller omits (or passes an empty) `repo`, derive
@@ -628,7 +792,7 @@ export async function mirrorNarrative(opts) {
 
   const rawVaultDir = vaultIntegration['vault-dir'];
   if (!rawVaultDir || typeof rawVaultDir !== 'string') {
-    return { action: 'skipped-vault-disabled' };
+    return { result: { action: 'skipped-vault-disabled' } };
   }
 
   const vaultDir = path.resolve(expandHome(rawVaultDir));
@@ -640,9 +804,19 @@ export async function mirrorNarrative(opts) {
   const outputPath = resolveNarrativePath(vaultDir, repoSlug);
 
   // Defense-in-depth: ensure the resolved file stays inside the vault root.
-  const inside = validatePathInsideProject(path.relative(vaultDir, outputPath), vaultDir);
+  //
+  // `canonicalizeRoot: true` (#1033) is load-bearing, not hygiene. The guard's
+  // realpath phase is skipped while the target is ABSENT (ENOENT) and fires once
+  // it EXISTS — so on a vault root reached through a symlink, run 1 writes and
+  // run 2 resolves the file to the canonical path, reads it as outside the
+  // LEXICAL root, and returns `skipped-invalid-path` forever after. Canonicalizing
+  // the root makes both sides of the comparison the same kind of path. Same call
+  // shape as scripts/lib/reconcile/writer.mjs and scripts/lib/memory-proposals/store.mjs.
+  const inside = validatePathInsideProject(path.relative(vaultDir, outputPath), vaultDir, {
+    canonicalizeRoot: true,
+  });
   if (!inside.ok) {
-    return { action: 'skipped-invalid-path', path: outputPath };
+    return { result: { action: 'skipped-invalid-path', path: outputPath } };
   }
 
   // Read STATE.md (best-effort; absent STATE.md → nothing to mirror).
@@ -651,7 +825,7 @@ export async function mirrorNarrative(opts) {
   try {
     stateContents = await readFile(stateMdPath, 'utf8');
   } catch {
-    return { action: 'skipped-no-statemd', path: outputPath };
+    return { result: { action: 'skipped-no-statemd', path: outputPath } };
   }
 
   // #1025: the ONE masking site for the narrative mirror — after the frontmatter
@@ -660,5 +834,11 @@ export async function mirrorNarrative(opts) {
   const narrative = maskNarrative(extractNarrative(stateContents));
   const content = renderNarrative({ repo: repoName, narrative, now });
 
-  return writeNarrative({ outputPath, content, dryRun, fs: injectedFs });
+  // `chars` measures the document THIS call rendered — so it is present on
+  // `skipped-noop` and `dry-run` too, where the render happened but nothing
+  // landed. `action` is the field that says whether it landed.
+  return {
+    result: writeNarrative({ outputPath, content, dryRun, fs: injectedFs }),
+    chars: content.length,
+  };
 }

package/scripts/lib/vcs-repo-spec.mjs

@@ -227,17 +227,56 @@ const WRONG_FAMILY_HOST = {
   github: 'gitlab.com',
 };
 
+/** URI schemes that can name a supported Git remote. */
+const REMOTE_URI_PROTOCOLS = new Set(['http:', 'https:', 'ssh:']);
+
 /**
- * Extract the bare hostname from a git remote URL, handling both the HTTPS
- * (`https://host/owner/repo.git`) and SSH (`git@host:owner/repo.git`) forms.
- * Returns `null` for an unrecognized shape (never throws).
+ * Parse a URI-style remote only when it uses one of this module's supported
+ * protocols. The `URL` parser makes hostname/port handling consistent between
+ * HTTP(S) and URI-style SSH while scp-style SSH stays a separate grammar.
+ *
+ * @param {string} url
+ * @returns {URL|null}
+ */
+function parseRemoteUri(url) {
+  if (typeof url !== 'string' || !/^(?:https?|ssh):\/\//i.test(url)) return null;
+  try {
+    const parsed = new URL(url);
+    return REMOTE_URI_PROTOCOLS.has(parsed.protocol) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Extract the operational host from a git remote URL, handling HTTPS
+ * (`https://host/owner/repo.git`), scp-style SSH (`git@host:owner/repo.git`),
+ * and URI-style SSH (`ssh://git@host/owner/repo.git`) forms. A non-default
+ * URI port is preserved because callers may need it to address a self-hosted
+ * instance. Returns `null` for an unrecognized shape (never throws).
  *
  * @param {string} url
  * @returns {string|null}
  */
 function extractHost(url) {
-  const httpsMatch = /^https?:\/\/([^/]+)/i.exec(url);
-  if (httpsMatch) return httpsMatch[1].toLowerCase();
+  const parsed = parseRemoteUri(url);
+  if (parsed !== null) return parsed.host.toLowerCase() || null;
+  const sshMatch = /^[^@\s]+@([^:\s]+):/i.exec(url);
+  if (sshMatch) return sshMatch[1].toLowerCase();
+  return null;
+}
+
+/**
+ * Extract a bare hostname for VCS-family comparisons. This deliberately drops
+ * a URI port: `github.com:443` is still the public GitHub host, while the
+ * operational `extractHost()` value retains a non-default self-hosted port.
+ *
+ * @param {string} url
+ * @returns {string|null}
+ */
+function extractHostname(url) {
+  const parsed = parseRemoteUri(url);
+  if (parsed !== null) return parsed.hostname.toLowerCase() || null;
   const sshMatch = /^[^@\s]+@([^:\s]+):/i.exec(url);
   if (sshMatch) return sshMatch[1].toLowerCase();
   return null;
@@ -367,12 +406,12 @@ export function resolveRepoSpec({ repoRoot, vcs = 'gitlab', gitRun = defaultGitR
 }
 
 /**
- * Resolve the bare hostname of the matching remote, for use with
- * `glab api --hostname`/`gh api --hostname` — the `api` subcommand of both
- * CLIs does NOT accept `-R`/`--repo` (it has no repo concept), only a
- * `--hostname` flag to pin which instance the request targets. This is the
- * host-pinning counterpart to `resolveRepoSpec` for those api-only call
- * sites.
+ * Resolve the operational host of the matching remote, preserving a
+ * non-default self-hosted port for `glab api --hostname`/`gh api --hostname`.
+ * The `api` subcommand of both CLIs does NOT accept `-R`/`--repo` (it has no
+ * repo concept), only `--hostname` to pin which instance the request targets.
+ * This is the host-pinning counterpart to `resolveRepoSpec` for those api-only
+ * call sites.
  *
  * Applies the identical remote-preference-order + cross-family-guard
  * resolution as `resolveRepoSpec`, just returning the host instead of the
@@ -393,6 +432,136 @@ export function resolveRepoHost({ repoRoot, vcs, gitRun } = {}) {
   return isUnsafeForArgv(host) ? undefined : host;
 }
 
+/** Project-path characters that cannot name a GitLab namespace/project. */
+// eslint-disable-next-line no-control-regex -- validate every C0/C1 control before encoding a GitLab API path
+const UNSAFE_PROJECT_PATH_CHARS_RE = /[\\\x00-\x1f\x7f-\x9f?#]/;
+
+/**
+ * Decode a transport project path exactly once, then validate its canonical
+ * namespace/project shape. A percent sign surviving the one decode is rejected
+ * because `%252e%252e` is indistinguishable from a literal encoded escape; do
+ * not normalize that ambiguity into an API target.
+ *
+ * @param {string} rawProjectPath
+ * @param {{ uriPath: boolean }} opts
+ * @returns {string|undefined}
+ */
+function normalizeGitlabProjectPath(rawProjectPath, { uriPath }) {
+  if (typeof rawProjectPath !== 'string') return undefined;
+
+  let projectPath = rawProjectPath;
+  if (uriPath) {
+    // URI syntax supplies one separator before the path. More than one is a
+    // path segment, not syntax to trim away.
+    if (!projectPath.startsWith('/') || projectPath.startsWith('//')) return undefined;
+    projectPath = projectPath.slice(1);
+  }
+
+  if (
+    projectPath === '' ||
+    projectPath.startsWith('/') ||
+    projectPath.endsWith('/') ||
+    UNSAFE_PROJECT_PATH_CHARS_RE.test(projectPath)
+  ) {
+    return undefined;
+  }
+
+  let decodedProjectPath;
+  try {
+    decodedProjectPath = decodeURIComponent(projectPath);
+  } catch {
+    return undefined;
+  }
+
+  if (
+    decodedProjectPath.includes('%') ||
+    UNSAFE_PROJECT_PATH_CHARS_RE.test(decodedProjectPath) ||
+    isUnsafeForArgv(decodedProjectPath)
+  ) {
+    return undefined;
+  }
+
+  const withoutGitSuffix = decodedProjectPath.replace(/\.git$/i, '');
+  const segments = withoutGitSuffix.split('/');
+  if (
+    withoutGitSuffix === '' ||
+    withoutGitSuffix.startsWith('/') ||
+    withoutGitSuffix.endsWith('/') ||
+    segments.length < 2 ||
+    segments.some((segment) => segment === '' || segment === '.' || segment === '..')
+  ) {
+    return undefined;
+  }
+
+  return withoutGitSuffix;
+}
+
+/**
+ * Extract an operational GitLab host and the raw (not URL-normalized) project
+ * path. URI parsing owns authority/port validation, while the raw path keeps
+ * dot and percent-encoded traversal visible to {@link normalizeGitlabProjectPath}
+ * before WHATWG URL normalization could erase it.
+ *
+ * @param {string} url
+ * @returns {{ host: string, rawProjectPath: string, uriPath: boolean }|undefined}
+ */
+function extractGitlabProjectTargetParts(url) {
+  const scpMatch = /^[^@/\s]+@([^:/\s]+):(.+)$/.exec(url);
+  if (scpMatch) {
+    return { host: scpMatch[1], rawProjectPath: scpMatch[2], uriPath: false };
+  }
+
+  const parsed = parseRemoteUri(url);
+  if (
+    parsed === null ||
+    parsed.search !== '' ||
+    parsed.hash !== '' ||
+    ((parsed.protocol === 'http:' || parsed.protocol === 'https:') &&
+      (parsed.username !== '' || parsed.password !== ''))
+  ) {
+    return undefined;
+  }
+
+  // `parsed.pathname` is intentionally NOT used: the URL parser resolves
+  // `.`/`..` before this boundary can reject them. The regex reads only the
+  // path from an already-parsed, supported URI.
+  const rawPathMatch = /^[a-z][a-z0-9+.-]*:\/\/[^/?#]*(\/[^?#]*)?(?:[?#].*)?$/i.exec(url);
+  if (rawPathMatch === null) return undefined;
+  return { host: parsed.host, rawProjectPath: rawPathMatch[1] ?? '', uriPath: true };
+}
+
+/**
+ * Derive the API target for a GitLab project from the same sanitized,
+ * preference-selected remote that powers {@link resolveRepoSpec}. GitLab's REST
+ * API takes a URL-encoded `namespace/project` path rather than a remote URL or
+ * numeric project ID, so this projection removes the ambient project-metadata
+ * lookup from callers that need to pin both project and host.
+ *
+ * Supports HTTPS, scp-style SSH, and `ssh://` remotes. Credential stripping
+ * happens upstream in {@link listRemotes}; this helper returns only an
+ * operational host (including a non-default self-hosted port) and a once-only
+ * encoded project path, never a remote URL or HTTP userinfo. An SSH login such
+ * as `git@host` is transport identity, not project-path userinfo.
+ *
+ * @param {{ repoRoot?: string, gitRun?: GitRun }} [opts]
+ * @returns {{ host: string, encodedProjectPath: string }|undefined}
+ */
+export function resolveGitlabProjectTarget({ repoRoot, gitRun = defaultGitRun } = {}) {
+  const url = resolveRawRemoteUrl({ repoRoot, vcs: 'gitlab', gitRun });
+  if (!url) return undefined;
+
+  const parts = extractGitlabProjectTargetParts(url);
+  if (!parts || isUnsafeForArgv(parts.host)) return undefined;
+
+  const projectPath = normalizeGitlabProjectPath(parts.rawProjectPath, { uriPath: parts.uriPath });
+  if (!projectPath) return undefined;
+
+  return {
+    host: parts.host.toLowerCase(),
+    encodedProjectPath: encodeURIComponent(projectPath),
+  };
+}
+
 /**
  * @deprecated Back-compat alias for `archive-closed-prds.mjs`'s original
  * `defaultGlabRepo(repoRoot, gitRunFn)` positional signature (gitlab-only).
@@ -636,7 +805,7 @@ export function resolvePreferredRemote({ repoRoot, vcs, gitRun = defaultGitRun }
   const vcsPinned = vcs === 'github' || vcs === 'gitlab' ? vcs : null;
   const order = vcsPinned ? REMOTE_PREFERENCE[vcsPinned] : VCS_LESS_PREFERENCE;
   const wrongFamilyHost = vcsPinned ? WRONG_FAMILY_HOST[vcsPinned] : null;
-  const isWrongFamily = (url) => wrongFamilyHost !== null && extractHost(url) === wrongFamilyHost;
+  const isWrongFamily = (url) => wrongFamilyHost !== null && extractHostname(url) === wrongFamilyHost;
 
   /** @param {GitRemote} remote @param {'preference'|'sole-remote'} via */
   const accept = (remote, via) =>
@@ -670,7 +839,7 @@ export function resolvePreferredRemote({ repoRoot, vcs, gitRun = defaultGitRun }
  * @returns {{ family: 'gitlab'|'github', via: 'host-match'|'remote-name' }|null}
  */
 function classifyRemoteFamily(remote) {
-  const host = extractHost(remote.url);
+  const host = extractHostname(remote.url);
   if (host !== null) {
     if (host === 'github.com' || host.startsWith('github.')) return { family: 'github', via: 'host-match' };
     if (host === 'gitlab.com' || host.startsWith('gitlab.')) return { family: 'gitlab', via: 'host-match' };