@kici-dev/orchestrator 0.16.0 → 0.18.0

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

@@ -1,58 +1,56 @@
 /**
- * Filesystem-backed log storage.
+ * Filesystem-backed log storage: append-only JSONL files with cursor-based pagination.
+ * Lifecycle is operator-managed (the retention sweep runs on the S3 backend only).
  *
- * 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.
+ * Layout: {basePath}/executions/{runId}/job-{name}/step-{index}.log
  *
- * File layout:
- *   {basePath}/executions/{runId}/job-{name}/step-{index}.log
+ * A logical key maps to the same relative path on disk, `/` separating directories. On a
+ * Windows host, each character Windows refuses in a file name (`"`, `*`, `:`, `<`, `>`, `?`,
+ * `|`, `\` and the control characters 1-31) is stored as the private-use character
+ * U+F000 + its code, the mapping Cygwin uses for the same set. Every name Windows accepts maps
+ * to itself, so the mapping moves no file a Windows host could already write, and `list()`
+ * decodes the names back to logical keys.
  */
 import type { LogReadOptions, LogReadResult, LogStorage } from './log-storage.js';
 interface FilesystemLogStorageOptions {
     basePath: string;
+    /** Host platform; `win32` turns on the file-name mapping. Defaults to `process.platform`. */
+    platform?: NodeJS.Platform;
 }
 export declare class FilesystemLogStorage implements LogStorage {
     private readonly basePath;
+    private readonly mapWin32Names;
     constructor(options: FilesystemLogStorageOptions);
     /**
-     * Resolve a logical log path to an absolute filesystem path, refusing
-     * anything that would address a file outside the storage root.
+     * Resolve a logical log path to an absolute path, refusing anything 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.
+     * Two checks, deliberately. `assertSafeLogPath` is the effective gate on POSIX (a relative
+     * path with no `..` cannot resolve outside the root), so the comparison below is unreachable
+     * there. It stays as an independent statement of the invariant: it catches resolvers with
+     * extra escape hatches (win32 resolves drive-relative `C:foo` against that drive's cwd, a form
+     * the Windows name mapping already turns into a plain name), and 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.
+     * Both are lexical — neither resolves symlinks. A symlink planted inside the log root still
+     * redirects a clean path outside it; containing that needs a `realpath` per 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.
+     * Every verb funnels through here, so a new caller is contained on arrival.
      */
     private fullPath;
     /**
-     * Ensure the directory for a given file path exists.
+     * Logical key → relative on-disk path. Identity off Windows. On Windows a key that already
+     * holds one of the mapped private-use characters is refused: `list()` would decode it to a
+     * different key, so writing it would break the round trip.
      */
+    private toDiskPath;
+    /** Path relative to the base path, as the host separates it → logical `/`-separated key. */
+    private toLogicalKey;
     private ensureDir;
-    /**
-     * Check if a file exists on disk.
-     */
     private fileExists;
-    /**
-     * Get the size of a file in bytes. Returns 0 if the file doesn't exist.
-     */
+    /** Bytes; 0 if the file doesn't exist. */
     private fileSize;
-    /**
-     * Recursively list all files under a directory, returning paths relative
-     * to the base path.
-     */
+    /** Recursive; logical keys relative to the base path. */
     private listRecursive;
     append(path: string, data: string): Promise<void>;
     appendStreaming(path: string, data: string): Promise<void>;

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

@@ -1,9 +1,8 @@
 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.
+ * Shaped after the payload the execution tracker (the primary caller) hands its
+ * `onJobComplete` hook, plus the agent-supplied `data` blob for the enriched summary.
  */
 export interface JobCheckRunCompletionInput {
     runId: string;
@@ -14,11 +13,9 @@ export interface JobCheckRunCompletionInput {
     /** 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.
+     * Overrides the conclusion mapper's default wording with a reason the caller already
+     * holds — e.g. the queue-expiry sweep's `unroutable` message is the only statement of
+     * WHICH `runsOn` selectors went unmatched, which the mapper's phrasing cannot name.
      */
     description?: string;
 }
@@ -29,22 +26,17 @@ export interface JobCheckRunCompletionDeps {
     getExecutionContext: (runId: string) => ExecutionContext | undefined;
 }
 /**
- * Post the terminal conclusion for a job's check run.
+ * Every terminal job must resolve the check run `setPending()` created at trigger match.
+ * A check run left `queued` is not cosmetic: branch protection requiring it can never be
+ * satisfied, and a developer reads it as "still running" indefinitely.
  *
- * 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.
  *
- * 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.
+ * Never throws. Its callers are hot paths whose remaining work matters more: the
+ * tracker's terminal-job hook runs inside `onJobStatus`, ahead of the job-complete event
+ * and the needs/wave scheduler hooks, and the expiry sweep runs it per job in a loop.
+ * `buildJobFailureDescription` reads an agent-supplied payload, so a malformed
+ * `stepResults` entry can raise — 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

@@ -1,18 +1,14 @@
 /**
- * The single place that decides what happens to a step-log chunk.
+ * The single place that decides what happens to a step-log chunk. Both ingresses feed
+ * it — the local agent WebSocket handler and the coordinator's peer handler (chunks
+ * relayed by a worker orchestrator) — so a worker-dispatched job's logs are persisted,
+ * counted and forwarded exactly like a local one's.
  *
- * 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.resolveJobName`, the same
- * call `ExecutionTracker.onStepStatus` uses to fill `execution_steps.log_path`,
- * so the reader and the writer cannot disagree about the naming rule — the
- * resolver falls back to `dispatch_queue.job_name` during the dispatch window
- * before in-memory job state is populated, which is what stops an early chunk
- * from being persisted under an unreadable `job-{jobId}` path.
+ * The storage key comes from `executionTracker.resolveJobName`, the same call
+ * `ExecutionTracker.onStepStatus` uses to fill `execution_steps.log_path`, so reader and
+ * writer cannot disagree on naming. Its `dispatch_queue.job_name` fallback during the
+ * dispatch window, before in-memory job state exists, stops an early chunk from landing
+ * under an unreadable `job-{jobId}` path.
  */
 import type { LogStream } from '@kici-dev/engine';
 import type { LogWriter } from './log-writer.js';
@@ -40,9 +36,8 @@ export interface LogChunkSinkDeps {
         resolveJobName(runId: string, jobId: string): Promise<string>;
     };
     /**
-     * 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.
+     * Platform forward for browser fan-out; absent in independent mode. The caller wraps
+     * the `log.chunk` envelope, keeping this module free of Platform-protocol knowledge.
      */
     forwardToPlatform?: (chunk: NormalizedLogChunk) => void;
 }

package/dist/reporting/log-pull-handler.d.ts

@@ -1,28 +1,19 @@
 /**
- * Handler for log pull protocol messages on the orchestrator side.
- *
- * Responds to Platform requests for historical logs (log.request).
- * Reads from LogStorage, supports pagination via cursor/limit,
- * and filtering by jobName/stepIndex.
- *
- * Live logs flow via the push-based log.chunk -> BrowserFanOut path
- * and are not handled here.
+ * Answers Platform `log.request` messages for historical logs from LogStorage, with
+ * cursor/limit pagination and jobName/stepIndex filtering. Live logs flow via the
+ * push-based log.chunk -> BrowserFanOut path, not here.
  */
 import type { LogStorage } from './log-storage.js';
 import type { ExecutionTracker } from './execution-tracker.js';
 export interface LogPullHandlerDeps {
     logStorage: LogStorage;
     executionTracker: ExecutionTracker;
-    /** Callback to send response messages back over WS */
+    /** Sends response messages back over WS */
     send: (message: unknown) => void;
 }
 export declare class LogPullHandler {
     private readonly deps;
     constructor(deps: LogPullHandlerDeps);
-    /**
-     * Handle log.request -- read logs from storage and respond.
-     * Supports filtering by jobName and stepIndex, pagination via cursor/limit.
-     */
     handleRequest(msg: {
         messageId: string;
         executionId: string;

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

@@ -5,10 +5,9 @@ import type { LogStorage } from './log-storage.js';
  * 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.
+ * `ttlDays <= 0` disables the sweep (returns 0). One `deleteMany` (S3
+ * DeleteObjects) removes them, so a large sweep is a handful of API calls, not
+ * one per object. A delete failure is logged and does not abort the cleanup tick.
  *
  * @returns Number of objects deleted.
  */

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

@@ -1,49 +1,33 @@
 /**
- * Log storage abstraction for the orchestrator.
- *
- * Provides a pluggable backend interface for persisting execution logs.
- * 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
+ * Pluggable execution-log storage (FilesystemLogStorage, S3LogStorage). Retention on S3 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.
  *
  * 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 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 is 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.
+ * The `..` test is per-segment, not a substring match: `job-a..b` is legitimate.
  *
- * `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.
+ * `FilesystemLogStorage.fullPath()` re-states the 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.
- */
+/** Cursor-based pagination for large log files. */
 export interface LogReadResult {
-    /** The log content for this page */
     data: string;
     /** Byte offset cursor for the next read (pass to options.cursor) */
     cursor: number;
     /** True if the entire file has been read (cursor >= file size) */
     complete: boolean;
 }
-/**
- * Options for LogStorage.read().
- */
 export interface LogReadOptions {
     /** Byte offset to start reading from (0-based). Default: 0 */
     cursor?: number;
@@ -51,17 +35,14 @@ export interface LogReadOptions {
     limit?: number;
 }
 /**
- * Pluggable log storage interface.
- *
- * All operations are async. Retention is enforced by the cleanup sweep on the
- * S3 backend (see `pruneExpiredLogs`); the filesystem backend is operator-managed.
+ * 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, 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 lines, immediately durable; creates the file (and directories) if missing.
+     * For single-shot writers (webhook payloads, rerun payloads, orchestration logs) that
+     * write once and read back without any finalize call.
      */
     append(path: string, data: string): Promise<void>;
     /**
@@ -77,19 +58,16 @@ export interface LogStorage {
      * 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). */
+    /** Directory listing by prefix. */
     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.
+     * Every physical object under a prefix, `path` relative to the storage prefix. Unlike
+     * {@link LogStorage.list} it does NOT collapse S3 segment objects (`.../seg-NNNNNN`):
+     * the retention sweep must 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;
@@ -102,9 +80,6 @@ export interface LogStorage {
      */
     deleteMany(paths: string[]): Promise<number>;
 }
-/**
- * Configuration for creating a log storage backend.
- */
 type LogStorageConfig = {
     type: 'filesystem';
     basePath: string;
@@ -122,9 +97,6 @@ type LogStorageConfig = {
     /** Seal a step-log segment once the oldest buffered byte reaches this age (ms). */
     segmentFlushMs: number;
 };
-/**
- * Factory function to create the appropriate LogStorage backend.
- */
 export declare function createLogStorage(config: LogStorageConfig): LogStorage;
 export {};
 //# sourceMappingURL=log-storage.d.ts.map

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

@@ -1,24 +1,19 @@
 /**
- * Log writer that transforms agent log lines into JSONL and persists to LogStorage.
+ * Writes agent log lines as JSONL to LogStorage at executions/{runId}/job-{name}/step-{index}.log.
  *
- * Each log line is formatted as a JSON object with timestamp, level, message,
- * and metadata fields. Lines are written to the standard log path layout:
- * executions/{runId}/job-{name}/step-{index}.log
- *
- * 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.
+ * Writes use `appendStreaming`: the filesystem backend appends immediately (no buffering); the
+ * S3 backend buffers per step key and seals immutable append-only segments. `drain(runId)`
+ * awaits in-flight appends, 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;
-    /** Optional observer registry for broadcasting log chunks to CLI observers. */
+    /** Broadcasts log chunks to CLI observers. */
     observerRegistry?: ObserverRegistry;
-    /** Optional function to check if a run is a test run (for observer broadcasting). */
+    /** Only test runs are broadcast to observers. */
     isTestRun?: (runId: string) => boolean;
 }
 export declare class LogWriter {
@@ -26,66 +21,43 @@ export declare class LogWriter {
     private readonly observerRegistry?;
     private readonly isTestRun?;
     /**
-     * In-flight `logStorage.append` promises, keyed by runId. `appendChunk` is
-     * called fire-and-forget from the agent WS handler (it does not await the
-     * storage write), so a run can flip to a terminal status while the final
-     * log chunk's append is still pending. `drain(runId)` lets a reader (the
-     * test-run logs cursor endpoint) wait for those pending writes before it
-     * reports the stream as fully drained — without this, the `done` flag can
-     * be returned `true` while the last user-visible log line is not yet on
-     * disk, dropping it from a blocking `kici run remote` follow.
+     * In-flight appends per runId. The agent WS handler calls `appendChunk` fire-and-forget, so a
+     * run can turn terminal while its final chunk's append is pending. `drain(runId)` lets a reader
+     * (the test-run logs cursor endpoint) wait for them; otherwise `done` can be `true` before the
+     * last log line is on 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.
-     */
+    /** Paths written per run; `drain(runId)` finalizes each (a no-op on the filesystem backend). */
     private readonly runPaths;
     constructor(deps: LogWriterDeps);
     /**
-     * Await every in-flight log append for `runId` that was registered before
-     * 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.
+     * Await every append for `runId` registered before this call, then seal each step log's S3
+     * tail segment. Settles even if an append rejected (`appendChunk` already logged it): the
+     * point is ordering, not error propagation. Later appends are not waited on — a terminal run
+     * emits no further chunks, so the call-time snapshot is complete.
      */
     drain(runId: string): Promise<void>;
     /**
-     * Append log lines from an agent to storage in JSONL format.
-     *
-     * Each line is formatted as:
+     * Append agent lines as JSONL, one per line:
      * {"ts":"2026-01-01T00:00:00.000Z","level":"stdout","msg":"line content","meta":{}}
      *
-     * Also fans log chunks to connected observers for real-time streaming
-     * (test runs only, when observerRegistry is configured).
+     * Also fans chunks out to observers (test runs only, when observerRegistry is configured).
      *
-     * @param runId - Execution run ID
      * @param jobName - Job name (not job ID)
-     * @param stepIndex - Step index within the job (0-based)
-     * @param lines - Raw log lines from the agent
-     * @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`.
+     * @param stepIndex - 0-based
+     * @param timestamp - Epoch ms, from the agent message
+     * @param jobId - Required for observer broadcasting
+     * @param stream - Subprocess stream; absent (not reported) is recorded as `stdout`.
      */
     appendChunk(runId: string, jobName: string, stepIndex: number, lines: string[], timestamp: number, jobId?: string, stepName?: string, stream?: LogStream): Promise<void>;
     /**
-     * Make {@link drain} for `runId` wait for `pending` as it waits for an
-     * append.
+     * Make {@link drain} for `runId` wait for `pending` as it waits for an append.
      *
-     * For a caller that still has work to do before it can call
-     * {@link appendChunk} — resolving the job name that names the storage key.
-     * Registering only inside `appendChunk` leaves that work outside the
-     * snapshot: a run that completes while the name is being resolved is drained
-     * first, the chunk's append lands afterwards, and on object storage its
-     * segment is never sealed, so the chunk is never readable. A job whose setup
-     * fails sends its last setup lines immediately before its terminal status,
-     * which is exactly that window.
+     * For a caller with work left before {@link appendChunk} — resolving the job name that names
+     * the storage key. Otherwise a run completing mid-resolve is drained first, the append lands
+     * after, and on object storage its segment is never sealed, so the chunk is never readable. A
+     * job whose setup fails sends its last setup lines right before its terminal status: exactly
+     * that window.
      */
     trackPending(runId: string, pending: Promise<unknown>): void;
 }

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

@@ -1,12 +1,8 @@
 /**
- * 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.
+ * Convert a worker-relayed `peer.log.chunk` into log-sink chunks. The peer frame carries a
+ * timestamp and stream per line; the sink (and `LogWriter.appendChunk`) takes one per chunk.
+ * Grouping consecutive lines that agree on both is lossless and keeps line order. A worker
+ * gives a chunk's lines one timestamp and stream, so this yields one group in practice.
  */
 import type { PeerLogChunk } from '@kici-dev/engine';
 import type { NormalizedLogChunk } from './log-chunk-sink.js';

package/dist/reporting/run-aggregator.d.ts

@@ -69,18 +69,13 @@ export interface RunDetailJobLookups {
     }>>;
 }
 /**
- * The routing reason as a reader should see it.
+ * The routing reason as a reader should see it: only while the job is `pending`/`queued`.
  *
- * `routing_reason` is only meaningful while the job is still waiting to be
- * routed, and more than twenty call sites move a job out of `pending`/`queued`
- * — dispatch, cancel, the run-level failure cascades, the stale detector.
- * Requiring every one of them to also null the column would be fragile in the
- * one direction that matters: the site somebody forgets renders a finished job
- * as "waiting for an agent".
- *
- * So the guard lives here, at the read boundary both projections share, where
- * it cannot be forgotten by a writer that does not know this column exists.
- * The stale bytes may linger in the row; they are never shown.
+ * More than twenty call sites move a job out of those statuses (dispatch, cancel, the
+ * run-level failure cascades, the stale detector). Making each also null the column is
+ * fragile: the site somebody forgets renders a finished job as "waiting for an agent". So
+ * the guard sits at the read boundary both projections share; stale bytes may linger in the
+ * row but are never shown.
  */
 export declare function visibleRoutingReason(status: string, routingReason: string | null): string | null;
 /** Map queried job + step rows into the dashboard run-detail job DTO shape. */

package/dist/reporting/run-summary-fields.d.ts

@@ -1,7 +1,6 @@
 /**
- * The run fields every `onExecutionStatusChange` context built from an
- * in-memory run carries, in one place so a new column cannot be forwarded from
- * some status transitions and silently dropped from others.
+ * The run fields every `onExecutionStatusChange` context built from an in-memory run carries,
+ * in one place so no status transition silently drops a new column.
  */
 import type { ExecutionContext } from './execution-tracker.js';
 type RunSummaryKey = 'workflowName' | 'provider' | 'repoIdentifier' | 'workflowRepoIdentifier' | 'sha' | 'installationId' | 'requestId' | 'routingKey' | 'ref' | 'triggerEvent' | 'commitMessage' | 'parentRunId' | 'originalRunId' | 'triggeredBy' | 'triggeredByAgentLabel' | 'triggerActorUsername' | 'triggerActorUserId';
@@ -14,11 +13,9 @@ export declare function statusEpochField(epoch: number | null | undefined): {
     statusEpoch?: number;
 };
 /**
- * The shared part of a run's status-change context.
- *
- * `workflowRepoIdentifier` is copied only when set, because its presence is
- * what marks a cross-repository global run downstream. `localWorkingTree` is
- * left to the caller: only some transitions forward it.
+ * `workflowRepoIdentifier` is copied only when set: its presence marks a cross-repository
+ * global run downstream. `localWorkingTree` is left to the caller (only some transitions
+ * forward it).
  */
 export declare function runSummaryFields(run: RunSummarySource): Pick<ExecutionContext, RunSummaryKey | 'statusEpoch'>;
 export {};