@kici-dev/orchestrator 0.1.27 → 0.2.0

package/dist/reporting/execution-tracker.d.ts

@@ -13,7 +13,7 @@
  */
 import { type Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
-import { ExecutionRunStatus, type InitFailure, ScalerEventType } from '@kici-dev/engine';
+import { ExecutionRunStatus, type InitFailure, RunFailureClass, ScalerEventType, OrchLogPhase } from '@kici-dev/engine';
 import type { ObserverRegistry } from '../ws/observer-registry.js';
 import type { LogStorage } from './log-storage.js';
 import type { JobQueue } from '../queue/job-queue.js';
@@ -50,6 +50,12 @@ export interface ExecutionContext {
     triggerActorUsername?: string | null;
     /** Immutable provider user id of the triggering actor (preferred for resolution). */
     triggerActorUserId?: string | null;
+    /**
+     * Why a terminal run failed (`RunFailureClass`). Set on terminal-failed /
+     * cancelled runs; forwarded to the Platform on `execution.status` so managed
+     * subscriptions can match on it. Null/undefined for success or non-terminal.
+     */
+    failureClass?: RunFailureClass | null;
     /** Workflow-level concurrency config from the lock file. */
     concurrency?: {
         cancelInProgress?: boolean;
@@ -68,6 +74,8 @@ interface WorkflowCompleteCallbackData {
     }>;
     routingKey?: string;
     repo: string;
+    /** Why the run failed (`RunFailureClass`); carried onto the `__workflow_complete` event. */
+    failureClass?: string;
 }
 /** Data passed to the onJobComplete callback. */
 interface JobCompleteCallbackData {
@@ -78,6 +86,11 @@ interface JobCompleteCallbackData {
     routingKey?: string;
     repo: string;
     workflowName: string;
+    /**
+     * Job payload carried by the status update (step results, error, duration).
+     * Feeds the enriched check-run summary and the failure description.
+     */
+    data?: Record<string, unknown>;
 }
 export interface ExecutionTrackerDeps {
     db: Kysely<Database>;
@@ -145,12 +158,37 @@ export interface ExecutionTrackerDeps {
         metadata?: Record<string, unknown>;
         durationMs?: number | null;
     }) => void;
+    /**
+     * Optional live forward of orchestration/provisioning log lines to Platform,
+     * fired in addition to persisting them to `logStorage`. Platform fans these
+     * out to run-detail browser subscribers as `orch-log.lines`. Best-effort:
+     * a push failure must never break dispatch.
+     *
+     * SECURITY: like `onRunEventEmit`, this payload MUST NOT carry an `orgId`.
+     * The Platform attributes the tenant from `authState.orgId`.
+     */
+    onOrchLog?: (chunk: {
+        runId: string;
+        jobId: string;
+        phase: OrchLogPhase;
+        lines: string[];
+        ts: number;
+    }) => void;
     /** Optional log storage for writing per-job orchestration logs (JSONL). */
     logStorage?: LogStorage;
     /** Org ID for this orchestrator instance (used in run.event emission). */
     orgId?: string;
     /** Optional job queue for cascading run failures to dispatch_queue entries. */
     jobQueue?: JobQueue;
+    /**
+     * Resolves a routing key to its owning org (customer_id), used to populate
+     * `execution_runs.customer_id` at insert time so the concurrency-gate running
+     * count is scoped per tenant. Injected (bound to `(rk) => resolveOrgId(db, rk)`
+     * at construction) to keep the tracker free of a pipeline import cycle. When
+     * absent — or when a run has no routing key — the row falls back to the
+     * `'__default__'` column default (the no-source fallback org).
+     */
+    resolveOrgId?: (routingKey: string) => Promise<string>;
 }
 export declare class ExecutionTracker {
     private readonly db;
@@ -163,9 +201,11 @@ export declare class ExecutionTracker {
     private readonly onExecutionStatusChange?;
     private readonly onJobStatusChange?;
     private readonly onRunEventEmit?;
+    private readonly onOrchLog?;
     private readonly logStorage?;
     private readonly orgId?;
     private readonly jobQueue?;
+    private readonly resolveOrgIdFn?;
     private readonly runs;
     /**
      * Per-run async-mutex chain. `onJobStatus` and `addJobsToRun` mutate the same
@@ -200,6 +240,12 @@ export declare class ExecutionTracker {
     /** Callback fired when a job's needs are satisfied and it's ready for dispatch. */
     onJobReadyCallback?: (runId: string, jobName: string) => Promise<void>;
     constructor(deps: ExecutionTrackerDeps);
+    /**
+     * Resolve the owning org for an `execution_runs` row from its routing key.
+     * Falls back to the `'__default__'` org (the column default) when the run has
+     * no routing key or no resolver is injected (single-tenant / test contexts).
+     */
+    private resolveCustomerId;
     /**
      * Register a callback fired when a job's needs become satisfied.
      * The processor sets this to dispatch newly-ready jobs to agents.
@@ -254,7 +300,9 @@ export declare class ExecutionTracker {
     /** Immutable provider user id of the triggering actor. */
     triggerActorUserId?: string | null, 
     /** Agent provenance label when triggered through an agent credential. */
-    triggeredByAgentLabel?: string | null): Promise<void>;
+    triggeredByAgentLabel?: string | null, 
+    /** Pull-request number for PR-triggered runs; null/omitted for non-PR runs. */
+    prNumber?: number | null): Promise<void>;
     /**
      * Upsert one execution_jobs row per dispatched job (idempotent on
      * (run_id, job_id) to tolerate a race with an early `onJobStatus`). The
@@ -438,12 +486,17 @@ export declare class ExecutionTracker {
      */
     onBuildFailedBeforeTracking(runId: string, workflowName: string, provider: string, repoIdentifier: string, ref: string, sha: string, deliveryId: string | null, providerContext: Record<string, unknown>, routingKey: string, triggerEvent?: string, commitMessage?: string, failureReason?: string, initFailure?: InitFailure): Promise<void>;
     /**
-     * Insert a `failed` execution_runs row directly for an init failure that
-     * occurred BEFORE onExecutionStarted ran (so no in-memory state exists
-     * and no jobs were dispatched). Also writes the structured init_failure
-     * signal and fires onExecutionStatusChange so Platform's projection picks
-     * it up via the normal forward path. Idempotent: if a row already exists
-     * for this runId, the insert is a no-op (ON CONFLICT DO NOTHING).
+     * Write a `failed` execution_runs row directly for an init failure, and drop
+     * any in-memory run so the recorded failure is the run's final word. Also
+     * writes the structured init_failure signal and fires onExecutionStatusChange
+     * so Platform's projection picks it up via the normal forward path.
+     *
+     * An existing row for this runId is overwritten while it is still live —
+     * dispatch may already have registered the run before init failed — and left
+     * alone once it is terminal, so a run that genuinely finished is never
+     * rewritten as failed. When the guard leaves the row alone, the failure
+     * metric and the Platform forward are suppressed with it: this orchestrator
+     * did not record the init failure, so it must not report one.
      *
      * Closes the silent pre-run-failure gap — without this helper, secret /
      * install-secret / all-jobs-rejected early-exits in dispatch-matched-workflow
@@ -469,7 +522,11 @@ export declare class ExecutionTracker {
      * `execution_runs` row in the `held` state — alive and resumable — so the
      * dashboard run list surfaces the paused workflow. No jobs are tracked: the
      * workflow-scoped held_runs row + pending workflow context (written by the
-     * caller) keep the run from being counted complete. Idempotent on runId.
+     * caller) keep the run from being counted complete, and any in-memory run is
+     * dropped so jobs registered before the gate cannot roll it up.
+     *
+     * An existing row for this runId is flipped to `held` while it is still live
+     * and left alone once it is terminal — a finished run is never re-held.
      */
     recordRunHeld(args: {
         runId: string;
@@ -485,6 +542,13 @@ export declare class ExecutionTracker {
         reason: string;
         triggerEvent?: string;
         commitMessage?: string;
+        /**
+         * Pull-request number for PR-triggered holds; null/omitted for non-PR runs.
+         * Stamped so PR-scoped `/kici approve|reject` (which joins `execution_runs`
+         * on `pr_number`) can attribute the held run to its PR — a NULL leaves a
+         * security hold fail-closed unreachable by the comment path.
+         */
+        prNumber?: number | null;
     }): Promise<void>;
     /**
      * Flip a `held` run back to `pending` so the resumed dispatch can proceed
@@ -524,6 +588,54 @@ export declare class ExecutionTracker {
      * Check if all tracked jobs in a run have reached terminal state.
      */
     isRunComplete(runId: string): boolean;
+    /**
+     * Take a token holding a run open while some of its jobs are still to be
+     * registered. Returns true when a token was taken, false for an unknown or
+     * already-completed run (nothing to hold).
+     *
+     * Three registration windows need this. A run whose source-pack `__build__`
+     * job is dispatched first is registered with that job ALONE, and its real
+     * jobs are only dispatched once the build finishes. A deferred init job and a
+     * deferred dynamic entry each register their jobs from a fire-and-forget task
+     * that outlives the dispatch call. In every case, without a token the already
+     * -registered jobs reaching a terminal state satisfies {@link isRunComplete},
+     * so the run is finalized early: a terminal run status is written, the
+     * provider check is posted, and the status is forwarded to the Platform — all
+     * before a single real job has run.
+     *
+     * The hold is a counter on the in-memory run, read only by
+     * {@link isRunComplete} — deliberately NOT a synthetic entry in the run's job
+     * map. The job map is what every outward projection enumerates (the Platform
+     * `state.replay` snapshot and its `execution_jobs` mirror, the reported job
+     * count, the workflow-complete job results, the active-run summary), so a
+     * marker parked there would surface as a phantom pending job on the dashboard
+     * and an off-by-one job count for the length of the window. A counter holds
+     * the completion check open without being visible to any of them, and it
+     * writes no `execution_jobs` row, so it never surfaces as a phantom job.
+     * A token whose holder never settles keeps the run `running` until the stale
+     * detector reaps it — the same backstop that covers a job that never
+     * reports.
+     *
+     * Each token must be paired with exactly one {@link releasePendingJobsHold}.
+     */
+    holdRunForPendingJobs(runId: string): boolean;
+    /**
+     * Drop one token taken by {@link holdRunForPendingJobs}, and finalize the run
+     * if dropping the LAST one left every remaining job terminal.
+     *
+     * The re-evaluation matters for the same reason it does in `addJobsToRun`:
+     * once the last token is gone nothing else drives a completion check (no
+     * further `job.status` messages are coming for already-finished jobs), so a
+     * run whose jobs all finished while a token was held would otherwise hang in
+     * `running` forever. Only the last release may finalize — while any other
+     * token is outstanding more jobs are still on their way.
+     *
+     * Idempotent — a no-op when no token is outstanding. The count clamps at
+     * zero so a stray extra release cannot drive it negative, which would
+     * permanently un-hold the run and stop a genuinely outstanding token from
+     * holding it open.
+     */
+    releasePendingJobsHold(runId: string): Promise<void>;
     /**
      * Get the current overall status of a run.
      */
@@ -594,6 +706,7 @@ export declare class ExecutionTracker {
         triggeredBy?: string | null;
         triggeredByAgentLabel?: string | null;
         failureReason?: string;
+        failureClass?: RunFailureClass;
         jobCount: number;
         startedAt: number;
         completedAt?: number;
@@ -669,13 +782,35 @@ export declare class ExecutionTracker {
      * stale detector when memRun is still tracked locally — writes the
      * execution_runs terminal row, fires Platform-forwarding +
      * workflow-complete callbacks, and schedules in-memory pruning.
+     *
+     * The terminal write is clobber-guarded. If the guard rejects it (the run
+     * already finished through the normal path), only the pruning happens: the
+     * recomputed status is not this orchestrator's record of the run, so neither
+     * the callbacks nor the completion metrics may claim it.
      */
     private completeRunFromMemoryState;
+    /**
+     * Drop a finished run's in-memory state after a grace period, so a late
+     * status/heartbeat arriving just after completion still finds its run.
+     *
+     * This is the single owner of run-lifetime state teardown, so every
+     * run-lifetime map is cleared here — including `testRunIds`: a run finished by
+     * the stale detector rather than the normal completion path would otherwise
+     * leave its observer-broadcast marker behind for the process's lifetime.
+     * (`runLockTails` is deliberately not touched: it is keyed by runId but scoped
+     * to a lock's holders, and `withRunLock` drops its own entry on release.)
+     */
+    private scheduleRunPrune;
     /**
      * Path B helper: complete a run using DB rows only (crash recovery /
      * pruned runs). Loads jobs + run row from execution_jobs/execution_runs,
      * checks the all-terminal predicate + run-state guard, then writes the
      * terminal row and fires Platform-forwarding callbacks.
+     *
+     * The run-state read and the terminal write are separate statements, so the
+     * write carries its own clobber guard. If that guard rejects it — a
+     * concurrent normal completion landed in between — the callbacks and the
+     * completion metrics are suppressed with it.
      */
     private completeRunFromDbFallback;
     /**
@@ -714,10 +849,21 @@ export declare class ExecutionTracker {
      *
      * Per locked decision:
      * - success ONLY if ALL jobs pass (skipped jobs count as success)
-     * - failed if ANY job failed or timed_out_stale
+     * - failed if ANY job ended in a failure status (see `STATUS_FAILURE_CLASS`)
      * - cancelled if ANY job cancelled (and none failed)
      */
     private computeRunStatus;
+    /**
+     * Derive the failure class from a terminal run's job statuses. Null for
+     * success (and any non-terminal status). `timed_out_stale` / `drift_dropped`
+     * / `unroutable` jobs — a job that never dispatched, whose `runsOn` matched no
+     * agent, whose agent went silent, or that was dropped by a topology reroute —
+     * are infra-class and collapse to `timed_out`; any other `failed` run is a
+     * `step_failure` (a job actually ran and failed). `never_started` (init
+     * failure) and `dead_orchestrator` (Platform-detected) are stamped by their
+     * own paths, not here.
+     */
+    private computeFailureClass;
 }
 export {};
 //# sourceMappingURL=execution-tracker.d.ts.map

package/dist/reporting/fs-log-storage.d.ts

@@ -1,8 +1,9 @@
 /**
  * Filesystem-backed log storage.
  *
- * Stores execution logs as files on disk. No TTL -- logs persist indefinitely.
- * Supports append-only writes (JSONL accumulation) and cursor-based pagination.
+ * Stores execution logs as files on disk. Lifecycle is operator-managed (the
+ * cleanup retention sweep runs on the S3 backend only). Supports append-only
+ * writes (JSONL accumulation) and cursor-based pagination.
  *
  * File layout:
  *   {basePath}/executions/{runId}/job-{name}/step-{index}.log
@@ -14,6 +15,27 @@ interface FilesystemLogStorageOptions {
 export declare class FilesystemLogStorage implements LogStorage {
     private readonly basePath;
     constructor(options: FilesystemLogStorageOptions);
+    /**
+     * Resolve a logical log path to an absolute filesystem path, refusing
+     * anything that would address a file outside the storage root.
+     *
+     * Two checks, deliberately both. `assertSafeLogPath` is the effective gate on
+     * POSIX: once a path is relative and carries no `..` segment, `resolve()`
+     * cannot produce anything outside the root, so the comparison below is
+     * unreachable there. It is kept as a second, independent statement of the
+     * same invariant — it is what catches a resolver with extra escape hatches
+     * (win32 resolves a drive-relative `C:foo` against that drive's own cwd, not
+     * against the root), and it means relaxing the logical check cannot silently
+     * reopen an escape.
+     *
+     * Both checks are lexical — neither resolves symlinks. A symlink planted
+     * inside the log root still redirects a logically-clean path outside it;
+     * containing that would need a `realpath` on every call, and the log root is
+     * the orchestrator user's own directory.
+     *
+     * Every verb on this class funnels through here, so a new caller is
+     * contained on arrival.
+     */
     private fullPath;
     /**
      * Ensure the directory for a given file path exists.
@@ -33,9 +55,16 @@ export declare class FilesystemLogStorage implements LogStorage {
      */
     private listRecursive;
     append(path: string, data: string): Promise<void>;
+    appendStreaming(path: string, data: string): Promise<void>;
+    finalize(_path: string): Promise<void>;
     read(path: string, options?: LogReadOptions): Promise<LogReadResult>;
     exists(path: string): Promise<boolean>;
     list(prefix: string): Promise<string[]>;
+    listWithMetadata(prefix: string): Promise<Array<{
+        path: string;
+        lastModified: Date;
+    }>>;
+    deleteMany(paths: string[]): Promise<number>;
 }
 export {};
 //# sourceMappingURL=fs-log-storage.d.ts.map

package/dist/reporting/job-check-run-completion.d.ts

@@ -0,0 +1,50 @@
+import { type CheckRunReporter } from './check-run-reporter.js';
+import type { ExecutionContext } from './execution-tracker.js';
+/**
+ * Job-terminal signal this module reacts to. Shaped after the payload the
+ * execution tracker hands its `onJobComplete` hook — its primary caller — plus
+ * the agent-supplied `data` blob used to build the enriched check-run summary.
+ */
+export interface JobCheckRunCompletionInput {
+    runId: string;
+    jobId: string;
+    jobName: string;
+    /** Raw job status string as recorded by the tracker. */
+    status: string;
+    /** Agent-supplied job payload (step results, error, duration). */
+    data?: Record<string, unknown>;
+    /**
+     * Explicit check-run description, overriding the conclusion mapper's default
+     * wording. A caller that already holds the specific reason a job ended the way
+     * it did passes it here — the queue-expiry sweep's `unroutable` message, for
+     * instance, is the only statement of WHICH `runsOn` selectors went unmatched,
+     * and the mapper's generic phrasing cannot name them.
+     */
+    description?: string;
+}
+/** Collaborators needed to post a job's terminal check-run conclusion. */
+export interface JobCheckRunCompletionDeps {
+    checkRunReporter: Pick<CheckRunReporter, 'updateJobStatus'>;
+    /** Resolves the run's provider/repo/sha context — `ExecutionTracker.getExecutionContext`. */
+    getExecutionContext: (runId: string) => ExecutionContext | undefined;
+}
+/**
+ * Post the terminal conclusion for a job's check run.
+ *
+ * Every job that reaches a terminal state must resolve the check run that
+ * `setPending()` created for it at trigger match. A check run left `queued` is
+ * not cosmetic: branch protection that requires it can never be satisfied, and
+ * a developer reads it as "still running" indefinitely with nothing to point at.
+ *
+ * A non-terminal status is a no-op — a check run is completed once, when the job
+ * stops.
+ *
+ * Never throws. Its callers are hot paths whose remaining work matters more than
+ * this report: the tracker's terminal-job hook runs inside `onJobStatus`, ahead
+ * of the job-complete event emission and the needs/wave scheduler hooks, and the
+ * expiry sweep runs it per job inside a loop. `buildJobFailureDescription` reads
+ * an agent-supplied payload, so a malformed `stepResults` entry is enough to
+ * raise — and a check-run report is not worth stalling a run's scheduling for.
+ */
+export declare function reportJobCheckRunCompletion(deps: JobCheckRunCompletionDeps, input: JobCheckRunCompletionInput): void;
+//# sourceMappingURL=job-check-run-completion.d.ts.map

package/dist/reporting/log-chunk-sink.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The single place that decides what happens to a step-log chunk.
+ *
+ * Both ingresses feed this sink: the local agent WebSocket handler and the
+ * coordinator's peer handler, which receives chunks relayed by a worker
+ * orchestrator. Keeping the policy in one place is what makes the two paths
+ * behave identically — a worker-dispatched job's logs are persisted, counted
+ * and forwarded exactly like a locally-dispatched one's.
+ *
+ * The storage key is derived from `executionTracker.getJobName`, the same call
+ * `ExecutionTracker.onStepStatus` uses to fill `execution_steps.log_path`, so
+ * the reader and the writer cannot disagree about the naming rule.
+ */
+import type { LogStream } from '@kici-dev/engine';
+import type { LogWriter } from './log-writer.js';
+import type { StepLogBuffer } from './step-log-buffer.js';
+/** A chunk whose lines all share one timestamp and one originating stream. */
+export interface NormalizedLogChunk {
+    runId: string;
+    jobId: string;
+    stepIndex: number;
+    lines: string[];
+    timestamp: number;
+    stream?: LogStream;
+}
+/** Which ingress produced the chunk. Stamped onto the two log counters. */
+export type LogChunkSource = 'local' | 'peer';
+export interface LogChunkSinkDeps {
+    /** Ingress this sink instance serves; becomes the `source` metric attribute. */
+    source: LogChunkSource;
+    /** Short in-memory tail feeding the GitHub check-run summary. */
+    stepLogBuffer?: StepLogBuffer;
+    /** Durable step-log persistence. Absent when the orchestrator has no database. */
+    logWriter?: LogWriter;
+    /** Resolves the job name that names the storage path. */
+    executionTracker?: {
+        getJobName(runId: string, jobId: string): string | undefined;
+    };
+    /**
+     * Forward to the Platform for browser fan-out. Absent in independent mode.
+     * The caller wraps the chunk in the `log.chunk` envelope, which keeps this
+     * module free of Platform-protocol knowledge.
+     */
+    forwardToPlatform?: (chunk: NormalizedLogChunk) => void;
+}
+export declare function createLogChunkSink(deps: LogChunkSinkDeps): (chunk: NormalizedLogChunk) => void;
+//# sourceMappingURL=log-chunk-sink.d.ts.map

package/dist/reporting/log-retention.d.ts

@@ -0,0 +1,16 @@
+import type { LogStorage } from './log-storage.js';
+/**
+ * Delete step-log objects older than `ttlDays` in one bulk pass.
+ *
+ * Step-log objects are write-once (appended during the run, untouched after
+ * finalize), so last-modified time is the correct expiry basis — a recent or
+ * still-running run's objects were all written within the window and survive.
+ * `ttlDays <= 0` disables the sweep (returns 0). Expired objects are collected
+ * then bulk-deleted via `deleteMany` (S3 DeleteObjects), so a large sweep is a
+ * handful of API calls, not one-per-object. A delete failure is logged and the
+ * cleanup tick is not aborted.
+ *
+ * @returns Number of objects deleted.
+ */
+export declare function pruneExpiredLogs(storage: LogStorage, ttlDays: number, now?: Date): Promise<number>;
+//# sourceMappingURL=log-retention.d.ts.map

package/dist/reporting/log-storage.d.ts

@@ -2,14 +2,33 @@
  * Log storage abstraction for the orchestrator.
  *
  * Provides a pluggable backend interface for persisting execution logs.
- * Unlike CacheStorage, log storage has NO TTL semantics -- logs persist
- * indefinitely and the customer manages their own storage lifecycle.
+ * Retention on the S3 backend is bounded by the orchestrator cleanup sweep
+ * (`KICI_STEP_LOG_TTL_DAYS`, default 90; 0 disables it); the filesystem backend
+ * leaves lifecycle to the operator.
  *
  * Backends: FilesystemLogStorage, S3LogStorage
  *
  * Log file layout: executions/{runId}/job-{name}/step-{index}.log
  * Format: JSONL (one JSON object per line with timestamp, level, message, metadata)
  */
+/**
+ * Assert that a logical log path is safe to hand to a storage backend.
+ *
+ * The invariant every backend relies on: a log path is relative, contains no
+ * `..` segment, and carries no NUL byte. Both backends call this at their own
+ * boundary, so a malformed key is refused identically whichever backend the
+ * operator configured, and a new caller is guarded on arrival rather than by
+ * remembering to validate.
+ *
+ * The `..` test is per-segment, not a substring match: a job name such as
+ * `job-a..b` is legitimate and is accepted.
+ *
+ * `FilesystemLogStorage.fullPath()` re-states the same invariant physically,
+ * comparing the resolved absolute path against the resolved root. Both checks
+ * are lexical: neither resolves symlinks, so a symlink planted inside the log
+ * root still redirects a logically-clean path through it.
+ */
+export declare function assertSafeLogPath(path: string): void;
 /**
  * Read result from LogStorage.read().
  * Supports cursor-based pagination for large log files.
@@ -34,17 +53,54 @@ export interface LogReadOptions {
 /**
  * Pluggable log storage interface.
  *
- * All operations are async. No TTL -- logs persist indefinitely.
+ * All operations are async. Retention is enforced by the cleanup sweep on the
+ * S3 backend (see `pruneExpiredLogs`); the filesystem backend is operator-managed.
  */
 export interface LogStorage {
-    /** Append lines to a log file. Creates the file (and directories) if it doesn't exist. */
+    /**
+     * Append lines to a log file, immediately durable. Creates the file (and
+     * directories) if it doesn't exist. Used by single-shot writers (webhook
+     * payloads, rerun payloads, orchestration logs) that write once and expect
+     * the content to be readable without any subsequent finalize call.
+     */
     append(path: string, data: string): Promise<void>;
+    /**
+     * High-frequency append-only log write. Durability is guaranteed by a
+     * subsequent finalize(path) (called at run completion). S3 buffers per key
+     * and seals immutable segments on a size/time threshold; the filesystem
+     * appends immediately (appendFile is already durable).
+     */
+    appendStreaming(path: string, data: string): Promise<void>;
+    /**
+     * Seal any buffered-but-unwritten content for a path. S3 flushes its current
+     * tail segment; the filesystem is a no-op. Safe on any path — a no-op when
+     * nothing is buffered.
+     */
+    finalize(path: string): Promise<void>;
     /** Read log file content. Returns { data, cursor, complete } for pagination. */
     read(path: string, options?: LogReadOptions): Promise<LogReadResult>;
     /** Check if a log file exists. */
     exists(path: string): Promise<boolean>;
     /** List files matching a prefix (directory listing). */
     list(prefix: string): Promise<string[]>;
+    /**
+     * List every physical object under a prefix with its last-modified time,
+     * `path` relative to the storage prefix. Unlike {@link LogStorage.list} this
+     * does NOT collapse S3 segment objects (`.../seg-NNNNNN`) to their logical
+     * step path — the retention sweep must see and delete each physical object,
+     * and each segment carries its own last-modified time. Step-log objects are
+     * write-once, so last-modified is the correct expiry basis.
+     */
+    listWithMetadata(prefix: string): Promise<Array<{
+        path: string;
+        lastModified: Date;
+    }>>;
+    /**
+     * Bulk-delete objects by their storage-relative path (as returned by
+     * {@link LogStorage.listWithMetadata}). S3 uses `DeleteObjects` (≤1000
+     * keys/call, chunked); missing keys are no-ops. Returns the count deleted.
+     */
+    deleteMany(paths: string[]): Promise<number>;
 }
 /**
  * Configuration for creating a log storage backend.
@@ -61,6 +117,10 @@ type LogStorageConfig = {
     endpoint?: string;
     /** Use path-style access instead of virtual-hosted-style (required for most S3-compatible services) */
     forcePathStyle?: boolean;
+    /** Seal a step-log segment once the in-memory buffer reaches this many bytes. */
+    segmentFlushBytes: number;
+    /** Seal a step-log segment once the oldest buffered byte reaches this age (ms). */
+    segmentFlushMs: number;
 };
 /**
  * Factory function to create the appropriate LogStorage backend.

package/dist/reporting/log-writer.d.ts

@@ -5,10 +5,14 @@
  * and metadata fields. Lines are written to the standard log path layout:
  * executions/{runId}/job-{name}/step-{index}.log
  *
- * For filesystem storage, data is appended immediately (no buffering).
- * For S3 storage, the LogStorage backend handles read-concat-put.
+ * Step-log writes go through the high-frequency `appendStreaming` verb: the
+ * filesystem backend appends immediately (no buffering); the S3 backend buffers
+ * per step key and seals immutable append-only segments. `drain(runId)` awaits
+ * the in-flight appends and then finalizes each step path so the S3 tail
+ * segment is sealed before a reader declares the stream complete.
  */
 import type { LogStorage } from './log-storage.js';
+import { LogStream } from '@kici-dev/engine';
 import type { ObserverRegistry } from '../ws/observer-registry.js';
 interface LogWriterDeps {
     logStorage: LogStorage;
@@ -32,13 +36,22 @@ export declare class LogWriter {
      * disk, dropping it from a blocking `kici run remote` follow.
      */
     private readonly pendingAppends;
+    /**
+     * Log paths written for each run, populated in `appendChunk`. `drain(runId)`
+     * finalizes each one so the S3 backend seals its buffered tail segment before
+     * a reader declares the stream complete. The filesystem backend's `finalize`
+     * is a no-op.
+     */
+    private readonly runPaths;
     constructor(deps: LogWriterDeps);
     /**
      * Await every in-flight log append for `runId` that was registered before
-     * this call. Settles even if an append rejected (errors are already logged
-     * by `appendChunk`); the point is ordering, not error propagation. New
-     * appends started after this call are not waited on — a terminal run emits
-     * no further chunks, so the snapshot taken at call time is complete.
+     * this call, then seal each step log's buffered tail segment so the durable
+     * S3 record is complete. Settles even if an append rejected (errors are
+     * already logged by `appendChunk`); the point is ordering, not error
+     * propagation. New appends started after this call are not waited on — a
+     * terminal run emits no further chunks, so the snapshot taken at call time is
+     * complete.
      */
     drain(runId: string): Promise<void>;
     /**
@@ -57,8 +70,10 @@ export declare class LogWriter {
      * @param timestamp - Timestamp from the agent message (epoch ms)
      * @param jobId - Job ID for observer broadcasting (optional)
      * @param stepName - Step name for observer broadcasting (optional)
+     * @param stream - Which subprocess stream the lines came from. Absent means
+     *   the agent did not report one, which is recorded as `stdout`.
      */
-    appendChunk(runId: string, jobName: string, stepIndex: number, lines: string[], timestamp: number, jobId?: string, stepName?: string): Promise<void>;
+    appendChunk(runId: string, jobName: string, stepIndex: number, lines: string[], timestamp: number, jobId?: string, stepName?: string, stream?: LogStream): Promise<void>;
 }
 export {};
 //# sourceMappingURL=log-writer.d.ts.map

package/dist/reporting/peer-log-normalize.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Convert a worker-relayed `peer.log.chunk` into the chunk shape the log sink
+ * consumes.
+ *
+ * The peer frame carries a timestamp and an originating stream per line, while
+ * the sink (and `LogWriter.appendChunk` beneath it) takes one of each per
+ * chunk. Grouping consecutive lines that agree on both is lossless and keeps
+ * line order intact. A worker today gives every line in a chunk the same
+ * timestamp and stream, so this yields a single group in practice.
+ */
+import type { PeerLogChunk } from '@kici-dev/engine';
+import type { NormalizedLogChunk } from './log-chunk-sink.js';
+export declare function normalizePeerLogChunk(chunk: PeerLogChunk): NormalizedLogChunk[];
+//# sourceMappingURL=peer-log-normalize.d.ts.map