feat(staging-ff): classify workflow-scope push rejection distinctly (task-35e74651)

GitHub rejects the outbound staging→upstream FF push when a commit in the
range edits .github/workflows/ and the push token lacks the `workflow`
scope. This was misclassified as `other` → `error` → touchSentinel, hiding
the real cause behind a 24h throttle for a fix that takes seconds.

- classifyPushFailure: new "workflow-scope" class, matched BEFORE credentials
  (a 403 can partially match credentials; the more specific/actionable class
  must win). Tolerates ASCII-quote/backtick `workflow` and the OAuth-App
  `create or update workflow` anchor; the bare word `workflow` is not matched.
- syncUpstreamMainFromStaging step (E): new branch → outcome
  skipped-no-workflow-scope + staging_outbound_workflow_scope_missing event
  whose message names the cause + remedy (gh auth refresh -s workflow), and
  does NOT touch the sentinel (next tick retries, stale signal stays armed).
- runStagingOutboundPushTick: log the new outcome to stderr; persist the
  structured `project` on outbound events (and, symmetrically, inbound) so
  the annotation lookup matches by field, not message-prefix parsing.
- briefing-lag: stale outbound-sentinel note now appends cause + remedy read
  from the latest workflow-scope/credentials outbound event (new shared
  src/staging-event-meta.ts map + reader). Covers the symmetric credentials
  gap too (proposal Q2).

AC4 health-check finding annotation is scoped to the briefing-lag surface;
the health-check finding is inline skill bash with no src precompute to carry
the data, so skills/ludics-health-check.md stays unchanged (proposal Scope
lines 209-223). Noted as a documented gap, not closed this round.

Tests: classifier quote/phrasing variants + 403-ordering + non-ff control;
e2e positive (skipped-no-workflow-scope, event, sentinel NOT touched) +
negative control (non-ff → error, sentinel touched); reader unit
(ordering/project-filter/legacy-prefix/control); briefing-lag annotation
(workflow/credentials/control); mag e2e project-field persistence + stderr.

scope-expansion: new src/staging-event-meta.ts module (shared cause/remedy
map + reader) — proposal floated events.ts; neutral module avoids the
staging-ff↔briefing-lag import cycle and preserves staging-ff's events.ts
decoupling.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: lukstafi

src/briefing-lag.test.ts

@@ -269,4 +269,82 @@ describe("briefing-lag", () => {
     );
     expect(sentinelDirNoFile).not.toContain("outbound sentinel is");
   });
+
+  // task-35e74651: stale outbound-sentinel note carries a cause + remedy
+  // annotation read from the latest outbound push-auth event for the project.
+  function staleOutboundSetup(): { dir: string; sentinelDir: string; rg: RunGit } {
+    const dir = tmp();
+    const sentinelDir = mkdtempSync("/tmp/outbound-sentinel-");
+    mkdirSync(join(dir, ".git"), { recursive: true });
+    const sentinel = join(sentinelDir, "last-outbound-fast-forward-ocannl.epoch");
+    writeFileSync(sentinel, "");
+    const fiftyHoursAgo = new Date(Date.now() - 50 * 3600 * 1000);
+    utimesSync(sentinel, fiftyHoursAgo, fiftyHoursAgo);
+    const rg = fakeGit([
+      { match: ["remote"], stdout: "origin\nupstream\n" },
+      { match: ["symbolic-ref", "refs/remotes/origin/HEAD"], stdout: "refs/remotes/origin/master\n" },
+      { match: ["symbolic-ref", "refs/remotes/upstream/HEAD"], stdout: "refs/remotes/upstream/master\n" },
+      { match: ["rev-list"], stdout: "0\t0\n" },
+      { match: ["log"], stdout: "abc 2026-01-01 hi\n" },
+    ]);
+    return { dir, sentinelDir, rg };
+  }
+
+  function writeEvents(lines: Record<string, unknown>[]): string {
+    const evDir = mkdtempSync("/tmp/outbound-events-");
+    const file = join(evDir, "events.jsonl");
+    writeFileSync(file, lines.map((l) => JSON.stringify(l)).join("\n") + "\n");
+    return file;
+  }
+
+  test("formatUpstreamLagSection: stale outbound note includes workflow-scope cause/remedy", () => {
+    const { dir, sentinelDir, rg } = staleOutboundSetup();
+    const eventsFile = writeEvents([
+      { event_type: "staging_outbound_workflow_scope_missing", project: "ocannl", epoch: 100, message: "ocannl: x" },
+    ]);
+    const out = formatUpstreamLagSection(
+      [{ name: "ocannl", repo: "o/r", upstream_repo: "u/r", path: dir } as ProjectConfig],
+      { now: new Date(), runGit: rg, sentinelDir, eventsFile },
+    );
+    expect(out).toContain("outbound sentinel is");
+    expect(out).toContain("cause: push token lacks `workflow` scope");
+    expect(out).toContain("remedy: gh auth refresh -h github.com -s workflow");
+  });
+
+  test("formatUpstreamLagSection: stale outbound note includes credentials cause/remedy", () => {
+    const { dir, sentinelDir, rg } = staleOutboundSetup();
+    const eventsFile = writeEvents([
+      { event_type: "staging_outbound_credentials_missing", project: "ocannl", epoch: 100, message: "ocannl: x" },
+    ]);
+    const out = formatUpstreamLagSection(
+      [{ name: "ocannl", repo: "o/r", upstream_repo: "u/r", path: dir } as ProjectConfig],
+      { now: new Date(), runGit: rg, sentinelDir, eventsFile },
+    );
+    expect(out).toContain("cause: missing/invalid push credentials");
+    expect(out).toContain("remedy:");
+  });
+
+  test("formatUpstreamLagSection: stale outbound note is unannotated when no relevant event / no eventsFile", () => {
+    // Arm 1: eventsFile present but no matching event → base note only.
+    const a = staleOutboundSetup();
+    const eventsFile = writeEvents([
+      { event_type: "staging_outbound_fast_forwarded", project: "ocannl", epoch: 100, message: "ocannl: pushed" },
+    ]);
+    const out1 = formatUpstreamLagSection(
+      [{ name: "ocannl", repo: "o/r", upstream_repo: "u/r", path: a.dir } as ProjectConfig],
+      { now: new Date(), runGit: a.rg, sentinelDir: a.sentinelDir, eventsFile },
+    );
+    expect(out1).toContain("outbound sentinel is");
+    expect(out1).not.toContain("cause:");
+    expect(out1).not.toContain("remedy:");
+
+    // Arm 2: eventsFile omitted entirely → base note only (back-compat).
+    const b = staleOutboundSetup();
+    const out2 = formatUpstreamLagSection(
+      [{ name: "ocannl", repo: "o/r", upstream_repo: "u/r", path: b.dir } as ProjectConfig],
+      { now: new Date(), runGit: b.rg, sentinelDir: b.sentinelDir },
+    );
+    expect(out2).toContain("outbound sentinel is");
+    expect(out2).not.toContain("cause:");
+  });
 });

src/briefing-lag.ts

@@ -14,6 +14,7 @@ import { existsSync, statSync } from "fs";
 import { join } from "path";
 import type { ProjectConfig } from "./config.ts";
 import { detectDefaultBranches, expandHome, hasRemote, type RunGit } from "./git-runner.ts";
+import { latestOutboundCauseRemedy } from "./staging-event-meta.ts";
 
 export interface FormatLagOptions {
   now: Date;
@@ -30,6 +31,15 @@ export interface FormatLagOptions {
   sentinelDir?: string;
   /** Outbound sentinel age threshold for the stale annotation. Default 48h. gh-ludics-540. */
   outboundSentinelStaleSeconds?: number;
+  /**
+   * Path to the JSONL events file (`journal/events.jsonl`). When set, a stale
+   * outbound-sentinel note is annotated with the cause + remedy of the most
+   * recent outbound push-auth event for the project (workflow-scope /
+   * credentials). When omitted, the note is emitted without the annotation —
+   * backward-compatible with callers/tests that don't surface event data.
+   * task-35e74651.
+   */
+  eventsFile?: string;
 }
 
 /**
@@ -79,6 +89,7 @@ function outboundSentinelStaleNote(
   project: string,
   now: Date,
   stale: number,
+  eventsFile?: string,
 ): string | null {
   const sentinel = join(sentinelDir, `last-outbound-fast-forward-${project}.epoch`);
   if (!existsSync(sentinel)) return null;
@@ -87,7 +98,17 @@ function outboundSentinelStaleNote(
     const ageSec = Math.max(0, Math.floor((now.getTime() - mtime) / 1000));
     if (ageSec < stale) return null;
     const hours = Math.round(ageSec / 3600);
-    return `(outbound sentinel is ~${hours}h old; upstream push may be overdue)`;
+    let note = `(outbound sentinel is ~${hours}h old; upstream push may be overdue)`;
+    // task-35e74651: when the latest outbound push-auth event names a cause +
+    // remedy (workflow-scope / credentials), append it so the operator sees
+    // the copy-pasteable fix next to the stale-sentinel warning.
+    if (eventsFile) {
+      const annotation = latestOutboundCauseRemedy(eventsFile, project);
+      if (annotation) {
+        note += ` — cause: ${annotation.cause}; remedy: ${annotation.remedy}`;
+      }
+    }
+    return note;
   } catch {
     return null;
   }
@@ -156,7 +177,7 @@ export function formatUpstreamLagSection(
     // only creates it for opt-in projects).
     if (opts.sentinelDir) {
       const outboundStale = opts.outboundSentinelStaleSeconds ?? 48 * 3600;
-      const outboundNote = outboundSentinelStaleNote(opts.sentinelDir, name, opts.now, outboundStale);
+      const outboundNote = outboundSentinelStaleNote(opts.sentinelDir, name, opts.now, outboundStale, opts.eventsFile);
       if (outboundNote) lines.push(`- ${outboundNote}`);
     }
     lines.push("");

src/mag.test.ts

@@ -1,4 +1,4 @@
-import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync } from "fs";
 import { tmpdir } from "os";
 import { join } from "path";
@@ -1302,7 +1302,114 @@ function ocannlProject(opts: { enabled?: boolean | undefined; path?: string }):
   return base;
 }
 
+// task-35e74651: RunGit driver that reaches step (E)'s push and returns a
+// given push result. remote/status/branch-detect/fetch/local-ff/ancestry all
+// succeed so the push is the only failure point.
+function pushPathRunGit(push: { stdout?: string; stderr?: string; exitCode?: number }): RunGit {
+  return (args) => {
+    const key = args[0] ?? "";
+    if (key === "remote") return { stdout: "origin\nupstream\n", exitCode: 0 };
+    if (key === "status") return { stdout: "", exitCode: 0 };
+    if (key === "symbolic-ref") {
+      const ref = args[1] ?? "";
+      if (ref.endsWith("/origin/HEAD")) return { stdout: "refs/remotes/origin/master\n", exitCode: 0 };
+      if (ref.endsWith("/upstream/HEAD")) return { stdout: "refs/remotes/upstream/master\n", exitCode: 0 };
+      return { stdout: "", exitCode: 128 };
+    }
+    if (key === "rev-parse" && args[1] === "--abbrev-ref") return { stdout: "master\n", exitCode: 0 };
+    if (key === "checkout") return { stdout: "", exitCode: 0 };
+    if (key === "fetch") return { stdout: "", exitCode: 0 };
+    if (key === "merge" && args[1] === "--ff-only") return { stdout: "Already up to date.\n", exitCode: 0 };
+    if (key === "rev-list" && args[1] === "--count") return { stdout: "5\n", exitCode: 0 };
+    if (key === "merge-base" && args[1] === "--is-ancestor") return { stdout: "", exitCode: 0 };
+    if (key === "push") return { stdout: push.stdout ?? "", stderr: push.stderr, exitCode: push.exitCode ?? 0 };
+    return { stdout: "", exitCode: 0 };
+  };
+}
+
+const WORKFLOW_SCOPE_STDERR =
+  "! [remote rejected] origin/master -> master (refusing to allow an OAuth App to create or update workflow `.github/workflows/gh-pages-docs.yml` without `workflow` scope)";
+
 describe("runStagingOutboundPushTick", () => {
+  test("task-35e74651: workflow-scope push rejection persists event with structured project + remedy", () => {
+    const harnessRoot = mkdtempSync("/tmp/mag-outbound-wfscope-harness-");
+    const checkoutDir = mkdtempSync("/tmp/mag-outbound-wfscope-checkout-");
+    const ORIGINAL_HARNESS_DIR = process.env.LUDICS_HARNESS_DIR;
+    process.env.LUDICS_HARNESS_DIR = harnessRoot;
+    try {
+      const cfg = {
+        projects: [{
+          name: "ocannl",
+          repo: "lukstafi/ocannl-staging",
+          upstream_repo: "ahrefs/ocannl",
+          outbound_sync_enabled: true,
+          path: checkoutDir,
+        }],
+      } as unknown as LudicsFullConfig;
+      const results = runStagingOutboundPushTick({
+        isController: () => true,
+        runGit: pushPathRunGit({ stderr: WORKFLOW_SCOPE_STDERR, exitCode: 128 }),
+        config: cfg,
+        now: new Date(),
+        // sentinelDir omitted → emitEvent writes under env-overridden harnessRoot.
+      });
+      expect(results).toHaveLength(1);
+      expect(results[0]!.outcome).toBe("skipped-no-workflow-scope");
+
+      const eventsFile = join(harnessRoot, "journal", "events.jsonl");
+      expect(existsSync(eventsFile)).toBe(true);
+      const lines = readFileSync(eventsFile, "utf-8").trim().split("\n").filter(Boolean);
+      const wf = lines
+        .map((l) => JSON.parse(l) as Record<string, unknown>)
+        .filter((e) => e.event_type === "staging_outbound_workflow_scope_missing");
+      expect(wf).toHaveLength(1);
+      // Mutation guard for the new `project: ev.project` adapter line: drop it
+      // and this assertion fails (the annotation lookup would then have to
+      // parse the message prefix).
+      expect(wf[0]!.project).toBe("ocannl");
+      expect(String(wf[0]!.message)).toContain("gh auth refresh -h github.com -s workflow");
+    } finally {
+      if (ORIGINAL_HARNESS_DIR === undefined) delete process.env.LUDICS_HARNESS_DIR;
+      else process.env.LUDICS_HARNESS_DIR = ORIGINAL_HARNESS_DIR;
+      rmSync(harnessRoot, { recursive: true, force: true });
+      rmSync(checkoutDir, { recursive: true, force: true });
+    }
+  });
+
+  test("task-35e74651: skipped-no-workflow-scope outcome is logged to stderr", () => {
+    const sentinelDir = mkdtempSync("/tmp/outbound-wfscope-stderr-");
+    const checkoutDir = mkdtempSync("/tmp/outbound-wfscope-stderr-checkout-");
+    const cfg = {
+      projects: [{
+        name: "ocannl",
+        repo: "lukstafi/ocannl-staging",
+        upstream_repo: "ahrefs/ocannl",
+        outbound_sync_enabled: true,
+        path: checkoutDir,
+      }],
+    } as unknown as LudicsFullConfig;
+    const spy = spyOn(console, "error").mockImplementation(() => {});
+    let logged: string[];
+    try {
+      const results = runStagingOutboundPushTick({
+        isController: () => true,
+        runGit: pushPathRunGit({ stderr: WORKFLOW_SCOPE_STDERR, exitCode: 128 }),
+        config: cfg,
+        sentinelDir,
+        now: new Date(),
+      });
+      expect(results[0]!.outcome).toBe("skipped-no-workflow-scope");
+      // Capture before restore (bun:test mockRestore wipes call history).
+      logged = spy.mock.calls.map((c) => String(c[0]));
+    } finally {
+      spy.mockRestore();
+      rmSync(sentinelDir, { recursive: true, force: true });
+      rmSync(checkoutDir, { recursive: true, force: true });
+    }
+    expect(logged.some((l) => l.includes("outbound-staging-ff ocannl: skipped-no-workflow-scope"))).toBe(true);
+  });
+
+
   test("controller-gate: short-circuits with zero git invocations when isController() returns false", () => {
     const { run, calls } = recordingRunGit();
     const sentinelDir = mkdtempSync("/tmp/outbound-gate-");

src/mag.ts

@@ -2071,13 +2071,14 @@ function runStagingFastForwardTick(): void {
       runGit: defaultRunGit,
       sentinelDir,
       emitEvent: (ev) => {
-        // Same `extra` forwarding as outbound — keeps the inbound and
-        // outbound adapter paths symmetric so future structured fields
-        // on the inbound flow (none today) don't get silently dropped.
+        // Same `extra` + `project` forwarding as outbound — keeps the inbound
+        // and outbound adapter paths symmetric so structured fields don't get
+        // silently dropped.
         emitEvent({
           event_type: ev.type,
           source: "mag",
           scope: "project",
+          project: ev.project,
           message: ev.message,
           ...(ev.extra ?? {}),
         });
@@ -2138,6 +2139,10 @@ export function runStagingOutboundPushTick(opts?: {
           event_type: ev.type,
           source: "mag",
           scope: "project",
+          // task-35e74651: persist the structured project so the briefing-lag
+          // cause/remedy annotation can match the latest outbound auth event
+          // by field instead of parsing the `${project}:` message prefix.
+          project: ev.project,
           message: ev.message,
           ...(ev.extra ?? {}),
         });
@@ -2148,6 +2153,7 @@ export function runStagingOutboundPushTick(opts?: {
         r.outcome === "pushed" ||
         r.outcome === "skipped-not-fast-forward" ||
         r.outcome === "skipped-no-push-credentials" ||
+        r.outcome === "skipped-no-workflow-scope" ||
         r.outcome === "skipped-local-staging-behind" ||
         r.outcome === "error"
       ) {
@@ -2275,6 +2281,10 @@ export async function briefingPrecomputeContext(opts?: { runGit?: RunGit }): Pro
     // "outbound sentinel stale > 48h" annotation alongside the
     // existing FETCH_HEAD freshness note.
     sentinelDir: join(harnessDir(), "mag"),
+    // task-35e74651: source for the cause/remedy annotation appended to a
+    // stale outbound-sentinel note (latest workflow-scope / credentials
+    // outbound event for the project).
+    eventsFile: join(harnessDir(), "journal", "events.jsonl"),
   });
   const upstreamLagSection = upstreamLag
     ? `## Upstream vs Staging Lag\n\n${upstreamLag.trimEnd()}\n\n`