@app-vitals/agent-runtime 0.3.0 → 0.5.0

package/boot.ts

@@ -31,6 +31,7 @@ import {
   planCronSchedule,
   runPeriodicPasses,
 } from "./agent-extension.ts";
+import { agentFeaturesRef } from "./agent-features-ref.ts";
 import { agentReposRef } from "./agent-repos-ref.ts";
 import {
   agentSlackMembershipRef,
@@ -50,7 +51,6 @@ import {
   setLiveClaudeConfig,
 } from "./claude.ts";
 import { bunExec, detectClaudeCodeVersion } from "./claude-version.ts";
-import { agentFeaturesRef } from "./agent-features-ref.ts";
 import { cleanupAfterDaysRef } from "./cleanup-after-days-ref.ts";
 import { SystemClock } from "./clock.ts";
 import { createConfig } from "./config.ts";
@@ -58,6 +58,7 @@ import { createContextStampReader } from "./context-stamp.ts";
 import { reportCronFailure } from "./cron-failure-reporter.ts";
 import type { CronHandlerDeps } from "./cron-handler.ts";
 import { handleCronRequest } from "./cron-handler.ts";
+import { createRunNowHonourer } from "./cron-run-now.ts";
 import {
   HttpCronRunReporter,
   NoopCronRunReporter,
@@ -84,6 +85,10 @@ import {
 import { HttpChatServiceClient } from "./http-chat-service-client.ts";
 import { buildLogPrefix } from "./log-prefix.ts";
 import { validatePiperVoice } from "./piper-voice.ts";
+import {
+  createRepoAccessProbe,
+  createRepoAccessTokenFor,
+} from "./repo-access-probe.ts";
 import {
   createFileSessionStore,
   startSessionPruner,
@@ -223,6 +228,17 @@ export async function startAgent(
           apiUrl: config.shipwright.apiUrl,
           agentId: config.shipwright.agentId,
           apiKey: config.shipwright.apiKey,
+          repoAccessProbe: createRepoAccessProbe({
+            fetch,
+            clock: SystemClock(),
+            log: (message) => console.log(message),
+            getRepos: () => agentReposRef.get(),
+            isEnabled: () => agentFeaturesRef.get()?.repoAccessCheck === true,
+            tokenFor: createRepoAccessTokenFor(
+              () => githubInstallationsManagerRef.get(),
+              process.env,
+            ),
+          }),
         })
       : new NoopGitHubInstallationsReporter();
 
@@ -684,6 +700,54 @@ export async function startAgent(
   const cronTasks = new Map<string, ReturnType<typeof nodeCron.schedule>>();
 
   if (runtimeClient && agentId) {
+    // Run-now requests (COS-42.1): honoured at most once each, in memory.
+    // Dispatch kind per job from the latest sync, so run-now takes the same
+    // path a scheduled tick would (loop-classified crons go through dispatchLoop).
+    let dispatchKinds = new Map<string, "loop" | "generic">();
+    const honourRunNow = createRunNowHonourer({
+      clock: SystemClock(),
+      dispatch: async (req) => {
+        if (dispatchKinds.get(req.jobId) === "loop") {
+          if (!extension.dispatchLoop) {
+            throw new Error(
+              `cron job ${req.jobId} classified as loop but the agent extension has no dispatchLoop`,
+            );
+          }
+          // dispatchLoop creates no run-now run of its own, so record one here:
+          // creating it clears the stamp and flips the audit row to honoured.
+          const reporter = cronRunReporter ?? new NoopCronRunReporter();
+          const startedAt = SystemClock().now();
+          const runId = await reporter.createRun(
+            req.jobId,
+            startedAt,
+            undefined,
+            undefined,
+            undefined,
+            req.commandVariant,
+          );
+          let outcome: "completed" | "failed" = "completed";
+          try {
+            await extension.dispatchLoop(req.jobId);
+          } catch (err) {
+            outcome = "failed";
+            throw err;
+          } finally {
+            await reporter
+              .completeRun(req.jobId, runId, SystemClock().now(), outcome)
+              .catch(() => {});
+          }
+          return;
+        }
+        await handleCronRequest(req, cronDeps);
+      },
+      onError: (jobId, err) =>
+        reportCronFailure(jobId, err, {
+          cronRunReporter: cronRunReporter ?? new NoopCronRunReporter(),
+          sentryClient: process.env.SENTRY_DSN ? Sentry : undefined,
+          clock: SystemClock(),
+        }),
+    });
+
     async function syncCrons() {
       if (!runtimeClient || !agentId) return;
       let jobs: Awaited<ReturnType<typeof runtimeClient.listAgentCronJobs>>;
@@ -705,6 +769,13 @@ export async function startAgent(
       // the coding extension's loop-cron-classifier.ts for the full decision.
       const scheduled = planCronSchedule(extension, jobs);
       const desired = new Map(scheduled.map((entry) => [entry.job.id, entry]));
+      dispatchKinds = new Map(
+        scheduled.map((entry) => [entry.job.id, entry.dispatch]),
+      );
+
+      // Fire-and-forget: a run can take minutes and must not hold up the sync.
+      // Only scheduled (enabled) jobs: a manually disabled cron is not run.
+      void honourRunNow(jobs.filter((job) => desired.has(job.id)));
 
       // Cancel removed/disabled jobs
       for (const [id, task] of cronTasks) {

package/cron-handler.ts

@@ -162,6 +162,8 @@ interface CronRequest {
   user?: string;
   silent?: boolean;
   preCheck?: string;
+  /** Run-attribution tag, e.g. "run-now" (COS-42.1); passed to createRun. */
+  commandVariant?: string;
 }
 
 export interface CronHandlerDeps {
@@ -266,7 +268,14 @@ export async function handleCronRequest(
 
   // CREATE run at start (before preCheck)
   const runId = cronRunReporter
-    ? await cronRunReporter.createRun(jobId, startedAt)
+    ? await cronRunReporter.createRun(
+        jobId,
+        startedAt,
+        undefined,
+        undefined,
+        undefined,
+        req.commandVariant,
+      )
     : null;
 
   // Best-effort redacted transcript upload (COS-43.1). Runs only after the

package/cron-handler.unit.test.ts

@@ -1176,6 +1176,34 @@ describe("handleCronRequest — telemetry forwarding", () => {
   });
 });
 
+describe("handleCronRequest — commandVariant (COS-42.1)", () => {
+  test("a run-now request creates its run with commandVariant run-now", async () => {
+    const created: unknown[][] = [];
+    const reporter: CronRunReporter = {
+      async createRun(...args: unknown[]) {
+        created.push(args);
+        return "run-now-1";
+      },
+      async completeRun() {},
+      async skipRun() {},
+      async recordProgress() {},
+      async recordSessionId() {},
+    };
+    await handleCronRequest(
+      {
+        jobId: "j-now",
+        prompt: "hello",
+        silent: true,
+        commandVariant: "run-now",
+      },
+      { ...deps, cronRunReporter: reporter },
+    );
+    expect(created).toHaveLength(1);
+    expect(created[0]?.[0]).toBe("j-now");
+    expect(created[0]?.[5]).toBe("run-now");
+  });
+});
+
 // ─── transcript upload hook (COS-43.1) ───────────────────────────────────────
 
 describe("handleCronRequest — transcript upload (COS-43.1)", () => {

package/cron-run-now.ts

@@ -0,0 +1,116 @@
+/**
+ * runtime/cron-run-now.ts
+ *
+ * Honours cron run-now requests (COS-42.1). The admin stamps
+ * `runRequestedAt` on a stored cron job; on each cron sync tick the runtime
+ * runs the job once when the stamp is strictly newer than the last one it
+ * honoured (held in memory) and at most 15 minutes old. An older stamp is
+ * logged as expired and never run. The request is dispatched with the job's
+ * own stored fields, never a prompt from anywhere else, and tagged
+ * commandVariant "run-now" so run creation clears the stamp admin-side.
+ */
+
+import type { Clock } from "./clock.ts";
+
+/** A request older than this is expired and never run. */
+export const RUN_NOW_FRESH_MS = 15 * 60_000;
+
+/** The stored cron job fields the honourer reads. */
+export interface RunNowJob {
+  id: string;
+  prompt: string;
+  channel?: string | null;
+  user?: string | null;
+  silent?: boolean;
+  preCheck?: string | null;
+  /** A manually disabled job is never run, even with a fresh stamp. */
+  enabled?: boolean;
+  /** ISO string on the wire (typed Date by the generated client). */
+  runRequestedAt?: string | Date | null;
+}
+
+export interface RunNowRequest {
+  jobId: string;
+  prompt: string;
+  channel?: string;
+  user?: string;
+  silent?: boolean;
+  preCheck?: string;
+  commandVariant: "run-now";
+}
+
+interface RunNowHonourerDeps {
+  clock: Clock;
+  /** Runs the job (handleCronRequest in production). */
+  dispatch: (req: RunNowRequest) => Promise<void>;
+  /** Called when a dispatch throws; the request is not retried. */
+  onError?: (jobId: string, err: unknown) => void | Promise<void>;
+  log?: (line: string) => void;
+}
+
+/**
+ * Returns a function to call with the fresh job list on every sync tick. It
+ * resolves once every dispatch it started has settled; callers that must not
+ * wait on long runs simply do not await it.
+ */
+export function createRunNowHonourer(
+  deps: RunNowHonourerDeps,
+): (jobs: readonly RunNowJob[]) => Promise<void> {
+  const { clock, dispatch, onError, log = console.log } = deps;
+  // jobId -> last honoured / last expired-logged runRequestedAt (epoch ms).
+  const lastHonoured = new Map<string, number>();
+  const expiredLogged = new Map<string, number>();
+
+  return async (jobs) => {
+    const running: Promise<void>[] = [];
+    for (const job of jobs) {
+      if (!job.runRequestedAt || job.enabled === false) continue;
+      const requestedMs = new Date(job.runRequestedAt).getTime();
+      if (Number.isNaN(requestedMs)) continue;
+      const requested = new Date(requestedMs).toISOString();
+
+      const seen = lastHonoured.get(job.id);
+      if (seen !== undefined && requestedMs <= seen) continue;
+
+      if (clock.now().getTime() - requestedMs > RUN_NOW_FRESH_MS) {
+        if (expiredLogged.get(job.id) !== requestedMs) {
+          expiredLogged.set(job.id, requestedMs);
+          log(
+            JSON.stringify({
+              event: "cron-run-now",
+              status: "expired",
+              jobId: job.id,
+              requestedAt: requested,
+            }),
+          );
+        }
+        continue;
+      }
+
+      // Recorded before dispatch so a slow or failing run is never repeated.
+      lastHonoured.set(job.id, requestedMs);
+      log(
+        JSON.stringify({
+          event: "cron-run-now",
+          status: "honouring",
+          jobId: job.id,
+          requestedAt: requested,
+        }),
+      );
+      running.push(
+        dispatch({
+          jobId: job.id,
+          prompt: job.prompt,
+          channel: job.channel ?? undefined,
+          user: job.user ?? undefined,
+          silent: job.silent,
+          preCheck: job.preCheck ?? undefined,
+          commandVariant: "run-now",
+        }).catch(async (err) => {
+          await onError?.(job.id, err);
+        }),
+      );
+    }
+    await Promise.all(running);
+  };
+}

package/cron-run-now.unit.test.ts

@@ -0,0 +1,156 @@
+/**
+ * runtime/cron-run-now.unit.test.ts
+ * Honour / expire / once logic for cron run-now requests (COS-42.1), with an
+ * injected clock and dispatch.
+ */
+
+import { describe, expect, it } from "bun:test";
+import {
+  createRunNowHonourer,
+  RUN_NOW_FRESH_MS,
+  type RunNowJob,
+} from "./cron-run-now.ts";
+
+const NOW = new Date("2026-10-26T12:00:00.000Z");
+
+function job(over: Partial<RunNowJob> = {}): RunNowJob {
+  return {
+    id: "job-1",
+    prompt: "stored prompt",
+    channel: "C1",
+    user: null,
+    silent: false,
+    preCheck: null,
+    runRequestedAt: null,
+    ...over,
+  };
+}
+
+function setup() {
+  let nowMs = NOW.getTime();
+  const dispatched: Array<Record<string, unknown>> = [];
+  const logs: string[] = [];
+  const honour = createRunNowHonourer({
+    clock: { now: () => new Date(nowMs) },
+    dispatch: async (req) => {
+      dispatched.push(req as unknown as Record<string, unknown>);
+    },
+    log: (line) => logs.push(line),
+  });
+  return {
+    honour,
+    dispatched,
+    logs,
+    advance: (ms: number) => {
+      nowMs += ms;
+    },
+  };
+}
+
+const ago = (ms: number) => new Date(NOW.getTime() - ms).toISOString();
+
+describe("createRunNowHonourer", () => {
+  it("never runs a manually disabled job", async () => {
+    const t = setup();
+    await t.honour([job({ enabled: false, runRequestedAt: ago(1000) })]);
+    expect(t.dispatched).toHaveLength(0);
+  });
+
+  it("runs a fresh request once with the stored job fields and run-now variant", async () => {
+    const { honour, dispatched } = setup();
+    await honour([job({ runRequestedAt: ago(60_000) })]);
+    expect(dispatched).toEqual([
+      {
+        jobId: "job-1",
+        prompt: "stored prompt",
+        channel: "C1",
+        user: undefined,
+        silent: false,
+        preCheck: undefined,
+        commandVariant: "run-now",
+      },
+    ]);
+  });
+
+  it("does not run the same request twice across ticks", async () => {
+    const { honour, dispatched, advance } = setup();
+    const j = job({ runRequestedAt: ago(60_000) });
+    await honour([j]);
+    advance(60_000);
+    await honour([j]);
+    await honour([j]);
+    expect(dispatched).toHaveLength(1);
+  });
+
+  it("runs again for a strictly newer request", async () => {
+    const { honour, dispatched, advance } = setup();
+    await honour([job({ runRequestedAt: ago(60_000) })]);
+    advance(120_000);
+    await honour([job({ runRequestedAt: ago(10_000) })]);
+    expect(dispatched).toHaveLength(2);
+  });
+
+  it("ignores an older-or-equal stamp than the last honoured", async () => {
+    const { honour, dispatched } = setup();
+    await honour([job({ runRequestedAt: ago(10_000) })]);
+    await honour([job({ runRequestedAt: ago(30_000) })]);
+    expect(dispatched).toHaveLength(1);
+  });
+
+  it("ignores a request older than 15 minutes and logs expired once", async () => {
+    const { honour, dispatched, logs } = setup();
+    const j = job({ runRequestedAt: ago(RUN_NOW_FRESH_MS + 1) });
+    await honour([j]);
+    await honour([j]);
+    expect(dispatched).toEqual([]);
+    const expired = logs.filter((l) => l.includes("expired"));
+    expect(expired).toHaveLength(1);
+    expect(logs.join("\n")).not.toContain("stored prompt");
+  });
+
+  it("a request exactly 15 minutes old is still fresh", async () => {
+    const { honour, dispatched } = setup();
+    await honour([job({ runRequestedAt: ago(RUN_NOW_FRESH_MS) })]);
+    expect(dispatched).toHaveLength(1);
+  });
+
+  it("a request that ages out between ticks without being seen expires", async () => {
+    const { honour, dispatched, logs, advance } = setup();
+    const j = job({ runRequestedAt: ago(0) });
+    advance(RUN_NOW_FRESH_MS + 60_000);
+    await honour([j]);
+    expect(dispatched).toEqual([]);
+    expect(logs.some((l) => l.includes("expired"))).toBe(true);
+  });
+
+  it("skips jobs with no request", async () => {
+    const { honour, dispatched, logs } = setup();
+    await honour([job(), job({ id: "job-2" })]);
+    expect(dispatched).toEqual([]);
+    expect(logs).toEqual([]);
+  });
+
+  it("a failing dispatch does not stop the other jobs and is not retried", async () => {
+    const dispatched: string[] = [];
+    const failures: string[] = [];
+    const honour = createRunNowHonourer({
+      clock: { now: () => NOW },
+      dispatch: async (req) => {
+        dispatched.push(req.jobId);
+        if (req.jobId === "bad") throw new Error("boom");
+      },
+      onError: (jobId) => {
+        failures.push(jobId);
+      },
+      log: () => {},
+    });
+    const jobs = [
+      job({ id: "bad", runRequestedAt: ago(1000) }),
+      job({ id: "good", runRequestedAt: ago(1000) }),
+    ];
+    await honour(jobs);
+    await honour(jobs);
+    expect(dispatched).toEqual(["bad", "good"]);
+    expect(failures).toEqual(["bad"]);
+  });
+});

package/cutover-validate.integration.test.ts

@@ -35,6 +35,8 @@ function makeCron(id: string): AgentCronJob {
     system: false,
     parentCronId: null,
     lockdownDisabledAt: null,
+    runRequestedAt: null,
+    runRequestedBy: null,
   };
 }
 

package/github-installations-reporter.ts

@@ -19,6 +19,7 @@ import type {
   InstallationState,
   InstallationsSnapshot,
 } from "./github-installations.ts";
+import type { RepoAccessEntry, RepoAccessProbe } from "./repo-access-probe.ts";
 
 export const INSTALLATIONS_HEARTBEAT_MS = 30 * 60 * 1000;
 const REQUEST_TIMEOUT_MS = 10_000;
@@ -56,6 +57,11 @@ interface HttpGitHubInstallationsReporterOptions {
   fetchFn?: typeof fetch;
   clock?: Clock;
   heartbeatMs?: number;
+  /**
+   * COS-44.1: per-repo access probe. It gates itself (flag, once per interval,
+   * scope change); the reporter just merges whatever it returns into the PUT.
+   */
+  repoAccessProbe?: RepoAccessProbe;
 }
 
 export class HttpGitHubInstallationsReporter
@@ -66,6 +72,7 @@ export class HttpGitHubInstallationsReporter
   private readonly heartbeatMs: number;
   private lastSignature: string | null = null;
   private lastPostedAt = 0;
+  private lastRepos: RepoAccessEntry[] | undefined;
 
   constructor(private opts: HttpGitHubInstallationsReporterOptions) {
     this.fetchFn = opts.fetchFn ?? fetch;
@@ -77,13 +84,19 @@ export class HttpGitHubInstallationsReporter
     try {
       const installations = snapshot.installations.map(toReported);
       const signature = JSON.stringify(installations);
+      const probed = await this.opts.repoAccessProbe?.run();
+      if (probed) this.lastRepos = probed;
       const nowMs = this.clock.now().getTime();
-      const changed = signature !== this.lastSignature;
+      const changed = signature !== this.lastSignature || probed !== undefined;
       if (!changed && nowMs - this.lastPostedAt < this.heartbeatMs) return;
       // Claim the slot before awaiting so overlapping reports don't double-post.
       this.lastSignature = signature;
       this.lastPostedAt = nowMs;
-      await this.put(installations, new Date(nowMs).toISOString());
+      await this.put(
+        installations,
+        new Date(nowMs).toISOString(),
+        this.lastRepos,
+      );
     } catch (err) {
       console.warn(
         `[github-installations-reporter] report failed: ${String(err)} — swallowing`,
@@ -94,6 +107,7 @@ export class HttpGitHubInstallationsReporter
   private async put(
     installations: ReportedInstallation[],
     reportedAt: string,
+    repos: RepoAccessEntry[] | undefined,
   ): Promise<void> {
     const { apiUrl, agentId, apiKey } = this.opts;
     const url = `${apiUrl}/agents/${agentId}/github-installations`;
@@ -104,7 +118,11 @@ export class HttpGitHubInstallationsReporter
           "Content-Type": "application/json",
           Authorization: `Bearer ${apiKey}`,
         },
-        body: JSON.stringify({ reportedAt, installations }),
+        body: JSON.stringify({
+          reportedAt,
+          installations,
+          ...(repos ? { repos } : {}),
+        }),
         signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
       });
       if (!res.ok) {

package/github-installations-reporter.unit.test.ts

@@ -5,6 +5,7 @@
 
 import { describe, expect, test } from "bun:test";
 import type { InstallationsSnapshot } from "./github-installations.ts";
+import type { RepoAccessEntry, RepoAccessProbe } from "./repo-access-probe.ts";
 import {
   HttpGitHubInstallationsReporter,
   INSTALLATIONS_HEARTBEAT_MS,
@@ -31,7 +32,10 @@ function snap(
   };
 }
 
-function harness(responses: (Response | Error)[] = []) {
+function harness(
+  responses: (Response | Error)[] = [],
+  repoAccessProbe?: RepoAccessProbe,
+) {
   let nowMs = Date.UTC(2026, 0, 1);
   const calls: { url: string; init: RequestInit | undefined }[] = [];
   let i = 0;
@@ -47,6 +51,7 @@ function harness(responses: (Response | Error)[] = []) {
     apiKey: "KEY",
     fetchFn,
     clock: { now: () => new Date(nowMs) },
+    repoAccessProbe,
   });
   return {
     reporter,
@@ -164,3 +169,48 @@ describe("NoopGitHubInstallationsReporter", () => {
     await new NoopGitHubInstallationsReporter().report(snap());
   });
 });
+
+describe("HttpGitHubInstallationsReporter repo access (COS-44.1)", () => {
+  const entry: RepoAccessEntry = {
+    repo: "a",
+    owner: "acme",
+    read: true,
+    write: false,
+    checkedAt: "2026-01-01T00:00:00.000Z",
+  };
+
+  test("a probe result is merged into the PUT body as repos", async () => {
+    const h = harness([], { run: async () => [entry] });
+    await h.reporter.report(snap());
+    expect(JSON.parse(String(h.calls[0].init?.body)).repos).toEqual([entry]);
+  });
+
+  test("a fresh probe result posts even when installations are unchanged", async () => {
+    let result: RepoAccessEntry[] | undefined = [entry];
+    const h = harness([], { run: async () => result });
+    await h.reporter.report(snap());
+    result = [{ ...entry, write: true }];
+    h.advance(60_000);
+    await h.reporter.report(snap());
+    expect(h.calls).toHaveLength(2);
+    expect(JSON.parse(String(h.calls[1].init?.body)).repos[0].write).toBe(true);
+  });
+
+  test("later heartbeats re-send the last probe result", async () => {
+    let result: RepoAccessEntry[] | undefined = [entry];
+    const h = harness([], { run: async () => result });
+    await h.reporter.report(snap());
+    result = undefined;
+    h.advance(INSTALLATIONS_HEARTBEAT_MS);
+    await h.reporter.report(snap());
+    expect(JSON.parse(String(h.calls[1].init?.body)).repos).toEqual([entry]);
+  });
+
+  test("no probe result -> body has no repos key", async () => {
+    const h = harness([], { run: async () => undefined });
+    await h.reporter.report(snap());
+    expect(
+      Object.keys(JSON.parse(String(h.calls[0].init?.body))).sort(),
+    ).toEqual(["installations", "reportedAt"]);
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@app-vitals/agent-runtime",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/app-vitals/agent.git",
@@ -40,8 +40,8 @@
     "./workspace-paths": "./workspace-paths.ts"
   },
   "dependencies": {
-    "@app-vitals/agent-admin": "0.3.0",
-    "@app-vitals/agent-lib": "0.3.0",
+    "@app-vitals/agent-admin": "0.5.0",
+    "@app-vitals/agent-lib": "0.5.0",
     "@octokit/auth-app": "^8.2.0",
     "@sentry/bun": "^10.63.0",
     "@slack/bolt": "^5.0.0",

package/repo-access-probe.ts

@@ -0,0 +1,193 @@
+/**
+ * runtime/repo-access-probe.ts
+ *
+ * Per-repo GitHub access probe (COS-44.1). For each repo in the agent's scope it
+ * calls GET /repos/{owner}/{repo} with the owner's installation token (or the
+ * PAT) and maps `permissions.pull` -> read, `permissions.push` -> write. A
+ * failure becomes read:false, write:false plus a fixed error class
+ * (not_found | forbidden | rate_limited | network).
+ *
+ * Gating lives here, not in the caller: run() does nothing (zero fetch calls)
+ * unless the feature flag is on, and then probes at most once per interval or
+ * when the repo scope changed. Concurrency is capped at 3. The token is passed
+ * only in the Authorization header — never logged, never in the result.
+ * Everything is injected so it is deterministically testable.
+ */
+
+import type { Clock } from "./clock.ts";
+
+export const REPO_ACCESS_INTERVAL_MS = 30 * 60 * 1000;
+const REPO_ACCESS_CONCURRENCY = 3;
+const REQUEST_TIMEOUT_MS = 10_000;
+
+export type RepoAccessErrorClass =
+  | "not_found"
+  | "forbidden"
+  | "rate_limited"
+  | "network";
+
+export interface RepoAccessEntry {
+  repo: string;
+  owner: string;
+  read: boolean;
+  write: boolean;
+  checkedAt: string;
+  error?: RepoAccessErrorClass;
+}
+
+export interface RepoAccessProbeDeps {
+  fetch: typeof fetch;
+  clock: Clock;
+  /** Token for the owner's installation, the PAT, or null when there is none. */
+  tokenFor(owner: string): Promise<string | null>;
+  log(message: string): void;
+  /** Scoped repos as `org/repo` strings. */
+  getRepos(): string[];
+  isEnabled(): boolean;
+  intervalMs?: number;
+}
+
+export interface RepoAccessProbe {
+  /**
+   * Returns a fresh result when a probe round ran, or undefined when it did
+   * not (feature off, or not due and the scope is unchanged).
+   */
+  run(): Promise<RepoAccessEntry[] | undefined>;
+}
+
+function classify(res: Response): RepoAccessErrorClass {
+  if (res.status === 404) return "not_found";
+  if (res.status === 429) return "rate_limited";
+  if (res.status === 403) {
+    return res.headers.get("x-ratelimit-remaining") === "0"
+      ? "rate_limited"
+      : "forbidden";
+  }
+  if (res.status === 401) return "forbidden";
+  return "network";
+}
+
+function failed(
+  owner: string,
+  repo: string,
+  checkedAt: string,
+  error: RepoAccessErrorClass,
+): RepoAccessEntry {
+  return { repo, owner, read: false, write: false, checkedAt, error };
+}
+
+export function createRepoAccessProbe(
+  deps: RepoAccessProbeDeps,
+): RepoAccessProbe {
+  const intervalMs = deps.intervalMs ?? REPO_ACCESS_INTERVAL_MS;
+  let lastScope: string | null = null;
+  let lastRunAt = 0;
+  let running = false;
+
+  async function probeOne(slug: string): Promise<RepoAccessEntry> {
+    const [owner = "", repo = ""] = slug.split("/");
+    const checkedAt = deps.clock.now().toISOString();
+    try {
+      const token = await deps.tokenFor(owner);
+      if (!token) return failed(owner, repo, checkedAt, "forbidden");
+      const res = await deps.fetch(
+        `https://api.github.com/repos/${owner}/${repo}`,
+        {
+          headers: {
+            Authorization: `Bearer ${token}`,
+            Accept: "application/vnd.github+json",
+          },
+          signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        },
+      );
+      if (!res.ok) return failed(owner, repo, checkedAt, classify(res));
+      const body = (await res.json()) as {
+        permissions?: { pull?: boolean; push?: boolean };
+      };
+      return {
+        repo,
+        owner,
+        read: body.permissions?.pull === true,
+        write: body.permissions?.push === true,
+        checkedAt,
+      };
+    } catch {
+      // Never interpolate the error: a thrown message could carry request detail.
+      return failed(owner, repo, checkedAt, "network");
+    }
+  }
+
+  async function probeAll(slugs: string[]): Promise<RepoAccessEntry[]> {
+    const results: RepoAccessEntry[] = new Array(slugs.length);
+    let next = 0;
+    const worker = async () => {
+      while (next < slugs.length) {
+        const i = next++;
+        results[i] = await probeOne(slugs[i] as string);
+      }
+    };
+    await Promise.all(
+      Array.from(
+        { length: Math.min(REPO_ACCESS_CONCURRENCY, slugs.length) },
+        worker,
+      ),
+    );
+    return results;
+  }
+
+  return {
+    async run() {
+      if (!deps.isEnabled() || running) return undefined;
+      const slugs = [...new Set(deps.getRepos())]
+        .filter((r) => r.includes("/"))
+        .sort();
+      const scope = slugs.join(",");
+      const nowMs = deps.clock.now().getTime();
+      const scopeChanged = scope !== lastScope;
+      if (!scopeChanged && nowMs - lastRunAt < intervalMs) return undefined;
+      running = true;
+      lastScope = scope;
+      lastRunAt = nowMs;
+      try {
+        const results = await probeAll(slugs);
+        deps.log(
+          `[repo-access] probed ${results.length} repo(s), ${results.filter((r) => r.error).length} with errors`,
+        );
+        return results;
+      } finally {
+        running = false;
+      }
+    },
+  };
+}
+
+interface InstallationTokenSource {
+  getState?(): {
+    installations: { id: number; owner: string | null; health: string }[];
+  };
+  /** Present on the real manager; the ref's narrower type omits it. */
+  getToken?(installationId: number): Promise<string>;
+}
+
+/**
+ * Builds `tokenFor`: the healthy installation whose owner matches (case
+ * insensitive), else the PAT from GH_TOKEN, else null. The manager is read
+ * lazily because App auth may activate after boot.
+ */
+export function createRepoAccessTokenFor(
+  getManager: () => InstallationTokenSource | null | undefined,
+  env: Readonly<Record<string, string | undefined>>,
+): (owner: string) => Promise<string | null> {
+  return async (owner) => {
+    const manager = getManager();
+    const match = manager
+      ?.getState?.()
+      .installations.find(
+        (i) =>
+          i.owner?.toLowerCase() === owner.toLowerCase() &&
+          i.health !== "broken",
+      );
+    if (manager?.getToken && match) return manager.getToken(match.id);
+    return env.GH_TOKEN || null;
+  };
+}

package/repo-access-probe.unit.test.ts

@@ -0,0 +1,211 @@
+/**
+ * runtime/repo-access-probe.unit.test.ts
+ * Probe behaviour via a routed fetch fake and an injected clock (COS-44.1).
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  createRepoAccessProbe,
+  createRepoAccessTokenFor,
+  REPO_ACCESS_INTERVAL_MS,
+} from "./repo-access-probe.ts";
+
+const SECRET = "ghs_SUPERSECRETTOKEN";
+
+type Route = Response | Error | ((req: { url: string }) => Response);
+
+function harness(
+  routes: Record<string, Route>,
+  opts: { repos?: string[]; enabled?: boolean; token?: string | null } = {},
+) {
+  let nowMs = Date.UTC(2026, 0, 1);
+  const calls: { url: string; auth: string | null }[] = [];
+  const logs: string[] = [];
+  let inFlight = 0;
+  let maxInFlight = 0;
+  const state = {
+    repos: opts.repos ?? ["acme/a"],
+    enabled: opts.enabled ?? true,
+  };
+  const fetchFn = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = String(input);
+    calls.push({
+      url,
+      auth: new Headers(init?.headers).get("authorization"),
+    });
+    inFlight++;
+    maxInFlight = Math.max(maxInFlight, inFlight);
+    await new Promise((r) => setTimeout(r, 1));
+    inFlight--;
+    const route = routes[url.replace("https://api.github.com/repos/", "")];
+    if (route instanceof Error) throw route;
+    if (typeof route === "function") return route({ url });
+    return route ?? new Response("{}", { status: 404 });
+  }) as unknown as typeof fetch;
+  const probe = createRepoAccessProbe({
+    fetch: fetchFn,
+    clock: { now: () => new Date(nowMs) },
+    tokenFor: async () => (opts.token === undefined ? SECRET : opts.token),
+    log: (m) => logs.push(m),
+    getRepos: () => state.repos,
+    isEnabled: () => state.enabled,
+  });
+  return {
+    probe,
+    calls,
+    logs,
+    state,
+    maxInFlight: () => maxInFlight,
+    advance: (ms: number) => {
+      nowMs += ms;
+    },
+  };
+}
+
+const ok = (pull: boolean, push: boolean) =>
+  new Response(JSON.stringify({ permissions: { pull, push } }), {
+    status: 200,
+  });
+
+describe("createRepoAccessProbe", () => {
+  test("maps permissions.pull/push to read/write", async () => {
+    const h = harness(
+      {
+        "acme/rw": ok(true, true),
+        "acme/ro": ok(true, false),
+      },
+      { repos: ["acme/rw", "acme/ro"] },
+    );
+    const result = await h.probe.run();
+    expect(result).toEqual([
+      expect.objectContaining({
+        repo: "ro",
+        owner: "acme",
+        read: true,
+        write: false,
+      }),
+      expect.objectContaining({
+        repo: "rw",
+        owner: "acme",
+        read: true,
+        write: true,
+      }),
+    ]);
+    expect(result?.every((r) => r.error === undefined)).toBe(true);
+    expect(result?.[0]?.checkedAt).toBe("2026-01-01T00:00:00.000Z");
+  });
+
+  test.each([
+    ["404", new Response("", { status: 404 }), "not_found"],
+    ["403", new Response("", { status: 403 }), "forbidden"],
+    [
+      "403 with exhausted rate limit",
+      new Response("", {
+        status: 403,
+        headers: { "x-ratelimit-remaining": "0" },
+      }),
+      "rate_limited",
+    ],
+    ["429", new Response("", { status: 429 }), "rate_limited"],
+    ["network error", new Error("ECONNRESET"), "network"],
+    ["5xx", new Response("", { status: 502 }), "network"],
+  ] as const)(
+    "%s -> read:false, write:false, error %s",
+    async (_n, route, error) => {
+      const h = harness({ "acme/a": route });
+      const result = await h.probe.run();
+      expect(result).toEqual([
+        expect.objectContaining({
+          repo: "a",
+          read: false,
+          write: false,
+          error,
+        }),
+      ]);
+    },
+  );
+
+  test("no credential for the owner -> forbidden without a fetch", async () => {
+    const h = harness({}, { token: null });
+    const result = await h.probe.run();
+    expect(result?.[0]?.error).toBe("forbidden");
+    expect(h.calls).toHaveLength(0);
+  });
+
+  test("feature off -> no calls and no result", async () => {
+    const h = harness({ "acme/a": ok(true, true) }, { enabled: false });
+    expect(await h.probe.run()).toBeUndefined();
+    expect(h.calls).toHaveLength(0);
+  });
+
+  test("at most once per interval, again after it elapses", async () => {
+    const h = harness({ "acme/a": ok(true, true) });
+    expect(await h.probe.run()).toBeDefined();
+    h.advance(REPO_ACCESS_INTERVAL_MS - 1);
+    expect(await h.probe.run()).toBeUndefined();
+    h.advance(1);
+    expect(await h.probe.run()).toBeDefined();
+    expect(h.calls).toHaveLength(2);
+  });
+
+  test("a scope change probes immediately", async () => {
+    const h = harness({ "acme/a": ok(true, true), "acme/b": ok(true, false) });
+    await h.probe.run();
+    h.state.repos = ["acme/a", "acme/b"];
+    const result = await h.probe.run();
+    expect(result).toHaveLength(2);
+    // Same set in a different order is not a change.
+    h.state.repos = ["acme/b", "acme/a"];
+    expect(await h.probe.run()).toBeUndefined();
+  });
+
+  test("concurrency is capped at 3", async () => {
+    const repos = Array.from({ length: 8 }, (_, i) => `acme/r${i}`);
+    const routes = Object.fromEntries(repos.map((r) => [r, ok(true, true)]));
+    const h = harness(routes, { repos });
+    await h.probe.run();
+    expect(h.calls).toHaveLength(8);
+    expect(h.maxInFlight()).toBe(3);
+  });
+
+  test("the token is sent only as a header and never logged or returned", async () => {
+    const h = harness({
+      "acme/a": new Error(`boom with ${SECRET}`),
+    });
+    const result = await h.probe.run();
+    expect(h.calls[0]?.auth).toBe(`Bearer ${SECRET}`);
+    expect(JSON.stringify(result)).not.toContain(SECRET);
+    expect(h.logs.join("\n")).not.toContain(SECRET);
+  });
+});
+
+describe("createRepoAccessTokenFor", () => {
+  const manager = {
+    getState: () => ({
+      installations: [
+        { id: 1, owner: "Acme", health: "ok" },
+        { id: 2, owner: "dead", health: "broken" },
+      ],
+    }),
+    getToken: async (id: number) => `inst-${id}`,
+  };
+
+  test("uses the matching healthy installation (case-insensitive)", async () => {
+    const tokenFor = createRepoAccessTokenFor(() => manager, {
+      GH_TOKEN: "pat",
+    });
+    expect(await tokenFor("acme")).toBe("inst-1");
+  });
+
+  test("falls back to the PAT, then null", async () => {
+    expect(
+      await createRepoAccessTokenFor(() => manager, { GH_TOKEN: "pat" })(
+        "dead",
+      ),
+    ).toBe("pat");
+    expect(
+      await createRepoAccessTokenFor(() => null, { GH_TOKEN: "pat" })("x"),
+    ).toBe("pat");
+    expect(await createRepoAccessTokenFor(() => null, {})("x")).toBeNull();
+  });
+});

package/shipwright-runtime-client.integration.test.ts

@@ -53,6 +53,8 @@ const SAMPLE_CRONS: AgentCronJob[] = [
     system: false,
     parentCronId: null,
     lockdownDisabledAt: null,
+    runRequestedAt: null,
+    runRequestedBy: null,
     createdAt: new Date("2025-01-01T00:00:00Z"),
     updatedAt: new Date("2025-01-01T00:00:00Z"),
   },