@app-vitals/agent-runtime 0.2.1 → 0.4.0

package/agent-features-ref.ts

@@ -0,0 +1,32 @@
+/**
+ * runtime/agent-features-ref.ts
+ *
+ * A tiny mutable box holding the `features` object from the most recently
+ * synced config bundle (COS-43.1), so consumers such as the transcript
+ * uploader read a live view without closing over one syncConfig() tick.
+ * Absent until the first successful sync (and when talking to an older admin
+ * that does not send `features`) — consumers treat that as "all off".
+ */
+
+export interface AgentFeatures {
+  transcriptUpload?: boolean;
+  repoAccessCheck?: boolean;
+}
+
+export interface AgentFeaturesRef {
+  get(): AgentFeatures | undefined;
+  set(features: AgentFeatures | undefined): void;
+}
+
+export function createAgentFeaturesRef(): AgentFeaturesRef {
+  let current: AgentFeatures | undefined;
+  return {
+    get: () => current,
+    set(features) {
+      current = features;
+    },
+  };
+}
+
+/** Process-wide ref written by boot's syncConfig() on every successful tick. */
+export const agentFeaturesRef: AgentFeaturesRef = createAgentFeaturesRef();

package/agent-features-ref.unit.test.ts

@@ -0,0 +1,21 @@
+/**
+ * runtime/agent-features-ref.unit.test.ts
+ * Tests an independent instance; the process-wide singleton is not mutated.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { createAgentFeaturesRef } from "./agent-features-ref.ts";
+
+describe("createAgentFeaturesRef", () => {
+  it("is undefined until set, then reflects the latest features", () => {
+    const ref = createAgentFeaturesRef();
+    expect(ref.get()).toBeUndefined();
+    ref.set({ transcriptUpload: true, repoAccessCheck: false });
+    expect(ref.get()).toEqual({
+      transcriptUpload: true,
+      repoAccessCheck: false,
+    });
+    ref.set(undefined);
+    expect(ref.get()).toBeUndefined();
+  });
+});

package/boot.ts

@@ -17,6 +17,7 @@
  *  8. Graceful SIGTERM/SIGINT shutdown
  */
 
+import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { initSentry } from "@app-vitals/agent-lib/sentry";
 import * as Sentry from "@sentry/bun";
@@ -49,6 +50,7 @@ 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";
@@ -56,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,
@@ -102,6 +105,7 @@ import {
   buildProductionDeps as buildSyncConfigCloneDeps,
   syncClonedRepos,
 } from "./sync-config-clone.ts";
+import { createTranscriptUploader } from "./transcript-uploader.ts";
 import { resolveDisplayName, resolveUserEmail } from "./users.ts";
 import { synthesizeSpeech, transcribeAudio } from "./voice.ts";
 import {
@@ -279,6 +283,25 @@ export async function startAgent(
     // GOR-1.3: cron spawns carry the default installation's org as the gh hint.
     getDefaultOwner: () =>
       defaultOwnerOf(githubInstallationsManagerRef.get()?.getState?.()),
+    // COS-43.1: redacted transcript upload after completeRun; gated by the
+    // synced features.transcriptUpload flag, failures swallowed.
+    ...(config.shipwright.apiUrl && config.shipwright.agentId
+      ? {
+          transcriptUploader: createTranscriptUploader({
+            fs: {
+              readFile: (path) => readFile(path, "utf8"),
+              readdir: (path) => readdir(path),
+            },
+            fetch,
+            clock: SystemClock(),
+            env: process.env,
+            log: (line) => console.warn(line),
+            apiUrl: config.shipwright.apiUrl,
+            agentId: config.shipwright.agentId,
+            getFeatures: () => agentFeaturesRef.get(),
+          }),
+        }
+      : {}),
   };
 
   // ARD-3.1: the specialty extension seam (agent-extension.ts). The consumer
@@ -527,6 +550,9 @@ export async function startAgent(
         // Sync the agent's cleanup-after-days live ref (APM-1.6) — read by the
         // runtime's worktree reaper.
         cleanupAfterDaysRef.set(bundle.cleanupAfterDays);
+
+        // Sync the feature flags (COS-43.1) — read by the transcript uploader.
+        agentFeaturesRef.set(bundle.features);
       } catch (err) {
         if (
           (err as { statusCode?: number }).statusCode === 404 &&
@@ -659,6 +685,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>>;
@@ -680,6 +754,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

@@ -33,6 +33,7 @@ import { parseMarkers } from "./markers.ts";
 import type { RunTelemetry } from "./run-telemetry.ts";
 import { dispatchMarkers, type SynthesizeSpeechFn } from "./slack.ts";
 import { buildSpawnEnv } from "./spawn-env.ts";
+import type { TranscriptUploader } from "./transcript-uploader.ts";
 import type { VoiceConfig } from "./voice.ts";
 
 /**
@@ -161,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 {
@@ -214,6 +217,11 @@ export interface CronHandlerDeps {
    * spawning ~15 real bun child processes per test run (CPS-1.1).
    */
   spawner?: typeof Bun.spawn;
+  /**
+   * Uploads the run's redacted session transcript once completeRun has been
+   * recorded (COS-43.1). Feature-gated inside the uploader; absent → no-op.
+   */
+  transcriptUploader?: TranscriptUploader;
 }
 
 export async function handleCronRequest(
@@ -244,6 +252,7 @@ export async function handleCronRequest(
     contextStamp,
     getDefaultOwner,
     spawner = Bun.spawn,
+    transcriptUploader,
   } = deps;
 
   const startedAt = clock.now();
@@ -259,9 +268,34 @@ 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
+  // run is recorded and can never fail or delay-fail the dispatch.
+  const uploadTranscript = async (sid: string | undefined): Promise<void> => {
+    if (!transcriptUploader || !runId) return;
+    try {
+      await transcriptUploader.upload({
+        cronId: jobId,
+        runId,
+        sessionId: sid,
+        cwd: workspace ?? process.cwd(),
+      });
+    } catch (err) {
+      console.warn(
+        `[agent:cron] transcript upload failed for run ${runId}: ${String(err)} — swallowing`,
+      );
+    }
+  };
+
   if (req.preCheck) {
     const isRelative =
       req.preCheck.startsWith("./") || req.preCheck.startsWith("../");
@@ -584,6 +618,7 @@ export async function handleCronRequest(
       ...tokenPayload,
       sessionId: failureSessionId,
     });
+    await uploadTranscript(failureSessionId);
     markCronRunFailureReported(err);
     throw err;
   }
@@ -602,6 +637,7 @@ export async function handleCronRequest(
       ...buildTokenPayload(usage, modelUsage, extras(telemetry)),
       sessionId,
     });
+    await uploadTranscript(sessionId);
     return;
   }
   const isDmOnly = !!user && !channel;
@@ -613,6 +649,7 @@ export async function handleCronRequest(
       ...buildTokenPayload(usage, modelUsage, extras(telemetry)),
       sessionId,
     });
+    await uploadTranscript(sessionId);
     return;
   }
 
@@ -627,6 +664,7 @@ export async function handleCronRequest(
       ...buildTokenPayload(usage, modelUsage, extras(telemetry)),
       sessionId,
     });
+    await uploadTranscript(sessionId);
     return;
   }
 
@@ -654,6 +692,7 @@ export async function handleCronRequest(
       ...buildTokenPayload(usage, modelUsage, extras(telemetry)),
       sessionId,
     });
+    await uploadTranscript(sessionId);
 
     // The run is already recorded as "completed" above — any error from here
     // on (postMessage, dispatchMarkers) must be tagged before rethrowing so
@@ -695,6 +734,7 @@ export async function handleCronRequest(
       ...buildTokenPayload(usage, modelUsage, extras(telemetry)),
       sessionId,
     });
+    await uploadTranscript(sessionId);
 
     // The run is already recorded as "completed" above — any error from here
     // on (conversations.open, postMessage, dispatchMarkers) must be tagged

package/cron-handler.unit.test.ts

@@ -1175,3 +1175,89 @@ describe("handleCronRequest — telemetry forwarding", () => {
     expect(completes[0]?.opts?.contextFingerprint).toBeUndefined();
   });
 });
+
+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)", () => {
+  function recordingReporter(order: string[]): CronRunReporter {
+    return {
+      async createRun() {
+        return "run-tx-1";
+      },
+      async completeRun() {
+        order.push("completeRun");
+      },
+      async skipRun() {},
+      async recordProgress() {},
+      async recordSessionId() {},
+    };
+  }
+
+  test("uploads after completeRun with the run's cron, run, session and cwd", async () => {
+    const order: string[] = [];
+    const calls: unknown[] = [];
+    await handleCronRequest(
+      { jobId: "j-tx", prompt: "hello", silent: true },
+      {
+        ...deps,
+        workspace: "/ws",
+        cronRunReporter: recordingReporter(order),
+        transcriptUploader: {
+          async upload(args) {
+            order.push("upload");
+            calls.push(args);
+          },
+        },
+      },
+    );
+    expect(order).toEqual(["completeRun", "upload"]);
+    expect(calls).toEqual([
+      { cronId: "j-tx", runId: "run-tx-1", sessionId: "sess-1", cwd: "/ws" },
+    ]);
+  });
+
+  test("an uploader rejection never fails the run", async () => {
+    await expect(
+      handleCronRequest(
+        { jobId: "j-tx2", prompt: "hello", silent: true },
+        {
+          ...deps,
+          cronRunReporter: recordingReporter([]),
+          transcriptUploader: {
+            async upload() {
+              throw new Error("boom");
+            },
+          },
+        },
+      ),
+    ).resolves.toBeUndefined();
+  });
+});

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@app-vitals/agent-runtime",
-  "version": "0.2.1",
+  "version": "0.4.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.2.1",
-    "@app-vitals/agent-lib": "0.2.1",
+    "@app-vitals/agent-admin": "0.4.0",
+    "@app-vitals/agent-lib": "0.4.0",
     "@octokit/auth-app": "^8.2.0",
     "@sentry/bun": "^10.63.0",
     "@slack/bolt": "^5.0.0",

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"),
   },

package/transcript-uploader.ts

@@ -0,0 +1,158 @@
+/**
+ * runtime/transcript-uploader.ts
+ * Uploads a redacted copy of a cron run's Claude session transcript to the
+ * admin API (COS-43.1) once the run is recorded.
+ *
+ * Gated by the synced config bundle's `features.transcriptUpload` (the admin
+ * flag SHIPWRIGHT_TRANSCRIPT_API_ENABLED). Redaction happens HERE, before the
+ * transcript leaves the pod: live SECRET_ENV_VARS values plus well-known token
+ * shapes (lib/redact.ts). The body is tail-truncated to 1 MiB on whole lines
+ * with a marker line first. Every failure logs one line (never the body) and
+ * is swallowed — an upload problem must never fail or alter a run.
+ *
+ * All I/O is injected ({ fs, fetch, clock, env, log }) so it is unit-testable.
+ */
+
+import { join } from "node:path";
+import { redact } from "@app-vitals/agent-lib/redact";
+import type { Clock } from "./clock.ts";
+
+/** Upload cap; the admin route 413s above it. */
+export const MAX_TRANSCRIPT_BYTES = 1024 * 1024;
+
+/** Bytes reserved for the truncation marker line. */
+const MARKER_RESERVE = 256;
+
+export interface TranscriptFs {
+  readFile(path: string): Promise<string>;
+  readdir(path: string): Promise<string[]>;
+}
+
+export interface TranscriptFeatures {
+  transcriptUpload?: boolean;
+}
+
+export interface TranscriptUploaderDeps {
+  fs: TranscriptFs;
+  fetch: typeof fetch;
+  clock: Clock;
+  env: Readonly<Record<string, string | undefined>>;
+  /** One-line logger; never receives transcript content. */
+  log: (line: string) => void;
+  apiUrl: string;
+  agentId: string;
+  /** The last synced `features` from the config bundle (absent before sync). */
+  getFeatures: () => TranscriptFeatures | undefined;
+}
+
+export interface TranscriptUploadArgs {
+  cronId: string;
+  runId: string;
+  sessionId: string | undefined;
+  /** The cwd the run's Claude process was spawned in. */
+  cwd: string;
+}
+
+export interface TranscriptUploader {
+  upload(args: TranscriptUploadArgs): Promise<void>;
+}
+
+/** Claude Code's project-dir naming: every "/" and "." becomes "-". */
+export function encodeCwd(cwd: string): string {
+  return cwd.replace(/[/.]/g, "-");
+}
+
+async function readTranscript(
+  deps: TranscriptUploaderDeps,
+  cwd: string,
+  sessionId: string,
+): Promise<string> {
+  const home = deps.env.AGENT_HOME ?? "";
+  const projects = join(home, "dot-claude", "projects");
+  const primary = join(projects, encodeCwd(cwd), `${sessionId}.jsonl`);
+  try {
+    return await deps.fs.readFile(primary);
+  } catch {
+    // Fall back to scanning every project dir for the session file.
+  }
+  for (const dir of await deps.fs.readdir(projects)) {
+    try {
+      return await deps.fs.readFile(join(projects, dir, `${sessionId}.jsonl`));
+    } catch {
+      // not in this project dir
+    }
+  }
+  throw new Error("transcript file not found");
+}
+
+/** Keeps whole trailing lines within the cap, prefixed by a marker line. */
+function tailTruncate(text: string): { body: string; truncated: boolean } {
+  if (Buffer.byteLength(text) <= MAX_TRANSCRIPT_BYTES) {
+    return { body: text, truncated: false };
+  }
+  const lines = text.split("\n");
+  if (lines[lines.length - 1] === "") lines.pop();
+  const budget = MAX_TRANSCRIPT_BYTES - MARKER_RESERVE;
+  let used = 0;
+  let keepFrom = lines.length;
+  while (keepFrom > 0) {
+    const size = Buffer.byteLength(lines[keepFrom - 1] as string) + 1;
+    if (used + size > budget) break;
+    used += size;
+    keepFrom--;
+  }
+  const marker = JSON.stringify({
+    type: "transcript-truncated",
+    note: "earlier lines dropped to fit the 1 MiB transcript cap",
+    droppedLines: keepFrom,
+    keptLines: lines.length - keepFrom,
+  });
+  const kept = lines.slice(keepFrom);
+  return {
+    body: `${marker}\n${kept.length ? `${kept.join("\n")}\n` : ""}`,
+    truncated: true,
+  };
+}
+
+export function createTranscriptUploader(
+  deps: TranscriptUploaderDeps,
+): TranscriptUploader {
+  return {
+    async upload({ cronId, runId, sessionId, cwd }) {
+      if (deps.getFeatures()?.transcriptUpload !== true) return;
+      if (!sessionId) return;
+      const apiKey = deps.env.SHIPWRIGHT_AGENT_API_KEY;
+      if (!apiKey) return;
+      const started = deps.clock.now().getTime();
+      try {
+        const raw = await readTranscript(deps, cwd, sessionId);
+        const { text, count } = redact(raw, deps.env);
+        const { body, truncated } = tailTruncate(text);
+        const url = `${deps.apiUrl}/agents/${deps.agentId}/crons/${cronId}/runs/${runId}/transcript`;
+        const res = await deps.fetch(url, {
+          method: "PUT",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${apiKey}`,
+          },
+          body: JSON.stringify({
+            sessionId,
+            body,
+            truncated,
+            redactions: count,
+          }),
+        });
+        if (!res.ok) {
+          deps.log(
+            `[transcript-upload] run ${runId} upload returned ${res.status} — skipped`,
+          );
+        }
+      } catch (err) {
+        const ms = deps.clock.now().getTime() - started;
+        deps.log(
+          `[transcript-upload] run ${runId} failed after ${ms}ms: ${err instanceof Error ? err.message : String(err)} — skipped`,
+        );
+      }
+    },
+  };
+}

package/transcript-uploader.unit.test.ts

@@ -0,0 +1,217 @@
+/**
+ * runtime/transcript-uploader.unit.test.ts
+ * COS-43.1: path resolution + fallback, truncation marker, feature off,
+ * redaction before upload, errors swallowed. All deps injected.
+ */
+
+import { describe, expect, it } from "bun:test";
+import {
+  createTranscriptUploader,
+  MAX_TRANSCRIPT_BYTES,
+  type TranscriptFs,
+} from "./transcript-uploader.ts";
+
+const HOME = "/data/agent-home";
+const CWD = "/data/agent-home/workspace";
+const ENCODED = "-data-agent-home-workspace";
+const SESSION = "sess-123";
+const PRIMARY = `${HOME}/dot-claude/projects/${ENCODED}/${SESSION}.jsonl`;
+
+function memFs(files: Record<string, string>): TranscriptFs {
+  return {
+    async readFile(path) {
+      const f = files[path];
+      if (f === undefined) throw new Error(`ENOENT ${path}`);
+      return f;
+    },
+    async readdir(path) {
+      const prefix = `${path}/`;
+      return [
+        ...new Set(
+          Object.keys(files)
+            .filter((p) => p.startsWith(prefix))
+            .map((p) => p.slice(prefix.length).split("/")[0] as string),
+        ),
+      ];
+    },
+  };
+}
+
+interface Call {
+  url: string;
+  init: RequestInit;
+}
+
+function setup(
+  files: Record<string, string>,
+  opts: {
+    features?: { transcriptUpload: boolean } | undefined;
+    status?: number;
+    throwFetch?: boolean;
+    env?: Record<string, string>;
+  } = {},
+) {
+  const calls: Call[] = [];
+  const logs: string[] = [];
+  const features =
+    "features" in opts ? opts.features : { transcriptUpload: true };
+  const uploader = createTranscriptUploader({
+    fs: memFs(files),
+    fetch: (async (url: string, init: RequestInit) => {
+      calls.push({ url, init });
+      if (opts.throwFetch) throw new Error("network down");
+      return new Response("{}", { status: opts.status ?? 200 });
+    }) as unknown as typeof fetch,
+    clock: { now: () => new Date("2026-10-26T00:00:00Z") },
+    env: {
+      AGENT_HOME: HOME,
+      SHIPWRIGHT_AGENT_API_KEY: "agent-key-xyz",
+      ...opts.env,
+    },
+    log: (l) => logs.push(l),
+    apiUrl: "https://admin.example",
+    agentId: "agent-1",
+    getFeatures: () => features,
+  });
+  const run = (sessionId: string | null = SESSION) =>
+    uploader.upload({
+      cronId: "cron-1",
+      runId: "run-1",
+      sessionId: sessionId ?? undefined,
+      cwd: CWD,
+    });
+  return { calls, logs, run };
+}
+
+describe("transcript uploader", () => {
+  it("PUTs the redacted transcript to the run's transcript path", async () => {
+    const { calls, run } = setup({ [PRIMARY]: '{"a":1}\n{"b":2}\n' });
+    await run();
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.url).toBe(
+      "https://admin.example/agents/agent-1/crons/cron-1/runs/run-1/transcript",
+    );
+    const init = calls[0]?.init as RequestInit;
+    expect(init.method).toBe("PUT");
+    expect((init.headers as Record<string, string>).Authorization).toBe(
+      "Bearer agent-key-xyz",
+    );
+    expect(JSON.parse(init.body as string)).toEqual({
+      sessionId: SESSION,
+      body: '{"a":1}\n{"b":2}\n',
+      truncated: false,
+      redactions: 0,
+    });
+  });
+
+  it("falls back to projects/*/<sessionId>.jsonl when the encoded cwd misses", async () => {
+    const other = `${HOME}/dot-claude/projects/-somewhere-else/${SESSION}.jsonl`;
+    const { calls, run } = setup({
+      [other]: "fallback\n",
+      [`${HOME}/dot-claude/projects/-x/other.jsonl`]: "nope\n",
+    });
+    await run();
+    expect(calls).toHaveLength(1);
+    expect(JSON.parse(calls[0]?.init.body as string).body).toBe("fallback\n");
+  });
+
+  it("encodes both / and . in the cwd", async () => {
+    const dotted = "/data/agent.home/work";
+    const p = `${HOME}/dot-claude/projects/-data-agent-home-work/${SESSION}.jsonl`;
+    const calls: string[] = [];
+    const up = createTranscriptUploader({
+      fs: memFs({ [p]: "ok\n" }),
+      fetch: (async (_u: string, init: RequestInit) => {
+        calls.push(init.body as string);
+        return new Response("{}");
+      }) as unknown as typeof fetch,
+      clock: { now: () => new Date() },
+      env: { AGENT_HOME: HOME, SHIPWRIGHT_AGENT_API_KEY: "k" },
+      log: () => {},
+      apiUrl: "https://a",
+      agentId: "a1",
+      getFeatures: () => ({ transcriptUpload: true }),
+    });
+    await up.upload({
+      cronId: "c",
+      runId: "r",
+      sessionId: SESSION,
+      cwd: dotted,
+    });
+    expect(calls).toHaveLength(1);
+  });
+
+  it("redacts secrets and reports the count", async () => {
+    const tok = `ghp_${"A1b2C3d4E5".repeat(3)}`;
+    const { calls, run } = setup({ [PRIMARY]: `line ${tok}\n` });
+    await run();
+    const body = JSON.parse(calls[0]?.init.body as string);
+    expect(body.body).not.toContain(tok);
+    expect(body.redactions).toBe(1);
+  });
+
+  it("tail-truncates to 1 MiB keeping whole lines with a marker first", async () => {
+    const line = `${JSON.stringify({ pad: "x".repeat(1000) })}\n`;
+    const count = Math.ceil((MAX_TRANSCRIPT_BYTES * 1.5) / line.length);
+    const lines = Array.from({ length: count }, (_, i) =>
+      JSON.stringify({ i, pad: "x".repeat(1000) }),
+    );
+    const { calls, run } = setup({ [PRIMARY]: `${lines.join("\n")}\n` });
+    await run();
+    const body = JSON.parse(calls[0]?.init.body as string);
+    expect(body.truncated).toBe(true);
+    expect(Buffer.byteLength(body.body)).toBeLessThanOrEqual(
+      MAX_TRANSCRIPT_BYTES,
+    );
+    const out = (body.body as string).split("\n").filter(Boolean);
+    expect(JSON.parse(out[0] as string).type).toBe("transcript-truncated");
+    // The kept tail is whole lines ending at the final input line.
+    expect(JSON.parse(out[out.length - 1] as string).i).toBe(count - 1);
+    for (const l of out) JSON.parse(l);
+  });
+
+  it("does nothing when the feature is off, absent, or sessionId unknown", async () => {
+    for (const features of [{ transcriptUpload: false }, undefined]) {
+      const { calls, run } = setup({ [PRIMARY]: "x\n" }, { features });
+      await run();
+      expect(calls).toHaveLength(0);
+    }
+    const { calls, run } = setup({ [PRIMARY]: "x\n" });
+    await run(null);
+    expect(calls).toHaveLength(0);
+  });
+
+  it("does nothing without an API key", async () => {
+    const { calls, run } = setup(
+      { [PRIMARY]: "x\n" },
+      { env: { SHIPWRIGHT_AGENT_API_KEY: "" } },
+    );
+    await run();
+    expect(calls).toHaveLength(0);
+  });
+
+  it("swallows a missing file, a fetch failure and a non-2xx with one log line each", async () => {
+    const missing = setup({});
+    await missing.run();
+    expect(missing.logs).toHaveLength(1);
+    expect(missing.calls).toHaveLength(0);
+
+    const thrown = setup({ [PRIMARY]: "x\n" }, { throwFetch: true });
+    await thrown.run();
+    expect(thrown.logs).toHaveLength(1);
+
+    const bad = setup({ [PRIMARY]: "x\n" }, { status: 500 });
+    await bad.run();
+    expect(bad.logs).toHaveLength(1);
+    expect(bad.logs[0]).toContain("500");
+  });
+
+  it("never logs the transcript body", async () => {
+    const { logs, run } = setup(
+      { [PRIMARY]: "TOP-SECRET-BODY\n" },
+      { status: 500 },
+    );
+    await run();
+    expect(logs.join("\n")).not.toContain("TOP-SECRET-BODY");
+  });
+});