adispatchd 0.0.0-stage → 0.1.0

package/dist/executors/env.js

@@ -0,0 +1,66 @@
+/**
+ * Worker environment (Spec §9.1, §20.3): workers never inherit the controller
+ * environment. They get a minimal set of standard variables, the explicitly
+ * declared `env`, resolved secrets and the `ADISPATCH_*` protocol variables.
+ */
+import { ADISPATCH_ENV } from '../core/index.js';
+/** Variables copied from the controller environment (if set). */
+export const MINIMAL_ENV_KEYS = ['PATH', 'HOME', 'LANG', 'TZ', 'USER', 'LOGNAME', 'TMPDIR'];
+/** PATH used when the controller has none. */
+export const FALLBACK_PATH = '/usr/local/bin:/usr/bin:/bin';
+/** Pick the minimal standard variables from `base` (default `process.env`). */
+export function buildMinimalEnv(base = process.env) {
+    const env = {};
+    for (const key of MINIMAL_ENV_KEYS) {
+        const value = base[key];
+        if (typeof value === 'string')
+            env[key] = value;
+    }
+    env.PATH ??= FALLBACK_PATH;
+    return env;
+}
+/**
+ * Extract a `source` block from any context object (main-worker context or a
+ * custom shell-action context). Returns `undefined` unless all fields are strings.
+ */
+export function contextSource(context) {
+    const source = context.source;
+    if (typeof source !== 'object' || source === null)
+        return undefined;
+    const { id, type, item_id, url } = source;
+    if (typeof id !== 'string' || typeof type !== 'string' || typeof item_id !== 'string' || typeof url !== 'string') {
+        return undefined;
+    }
+    return { id, type, item_id, url };
+}
+/** `ADISPATCH_*` variables for a worker (Spec §9.1). */
+export function buildOrchEnv(input) {
+    const env = {
+        [ADISPATCH_ENV.RUN_ID]: input.runId,
+        [ADISPATCH_ENV.WORKFLOW_ID]: input.workflowId,
+        [ADISPATCH_ENV.CONTEXT_FILE]: input.contextFile,
+        [ADISPATCH_ENV.RESULT_FILE]: input.resultFile,
+        [ADISPATCH_ENV.WORKSPACE]: input.workspace,
+    };
+    const source = contextSource(input.context);
+    if (source) {
+        env[ADISPATCH_ENV.SOURCE_TYPE] = source.type;
+        env[ADISPATCH_ENV.SOURCE_ID] = source.id;
+        env[ADISPATCH_ENV.SOURCE_ITEM_ID] = source.item_id;
+        env[ADISPATCH_ENV.SOURCE_URL] = source.url;
+    }
+    return env;
+}
+/**
+ * Compose the full worker environment. Precedence (later wins): minimal env
+ * < declared `env` < `secrets` < `ADISPATCH_*` (protocol variables cannot be overridden).
+ */
+export function buildWorkerEnv(parts) {
+    return {
+        ...buildMinimalEnv(parts.base),
+        ...parts.env,
+        ...parts.secrets,
+        ...parts.orch,
+    };
+}
+//# sourceMappingURL=env.js.map

package/dist/executors/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/executors/env.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,aAAa,EAAsB,MAAM,kBAAkB,CAAC;AAErE,iEAAiE;AACjE,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,CAAU,CAAC;AAErG,8CAA8C;AAC9C,MAAM,CAAC,MAAM,aAAa,GAAG,8BAA8B,CAAC;AAE5D,+EAA+E;AAC/E,MAAM,UAAU,eAAe,CAAC,IAAI,GAAsB,OAAO,CAAC,GAAG;IACnE,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,KAAK,MAAM,GAAG,IAAI,gBAAgB,EAAE,CAAC;QACnC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;QACxB,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IAClD,CAAC;IACD,GAAG,CAAC,IAAI,KAAK,aAAa,CAAC;IAC3B,OAAO,GAAG,CAAC;AACb,CAAC;AAUD;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,OAA0D;IACtF,MAAM,MAAM,GAAI,OAAgC,CAAC,MAAM,CAAC;IACxD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IACpE,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,MAAiC,CAAC;IACrE,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QACjH,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC;AACpC,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,YAAY,CAAC,KAO5B;IACC,MAAM,GAAG,GAA2B;QAClC,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,KAAK,CAAC,KAAK;QACnC,CAAC,aAAa,CAAC,WAAW,CAAC,EAAE,KAAK,CAAC,UAAU;QAC7C,CAAC,aAAa,CAAC,YAAY,CAAC,EAAE,KAAK,CAAC,WAAW;QAC/C,CAAC,aAAa,CAAC,WAAW,CAAC,EAAE,KAAK,CAAC,UAAU;QAC7C,CAAC,aAAa,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC,SAAS;KAC3C,CAAC;IACF,MAAM,MAAM,GAAG,aAAa,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC5C,IAAI,MAAM,EAAE,CAAC;QACX,GAAG,CAAC,aAAa,CAAC,WAAW,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC;QAC7C,GAAG,CAAC,aAAa,CAAC,SAAS,CAAC,GAAG,MAAM,CAAC,EAAE,CAAC;QACzC,GAAG,CAAC,aAAa,CAAC,cAAc,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC;QACnD,GAAG,CAAC,aAAa,CAAC,UAAU,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC;IAC7C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,KAK9B;IACC,OAAO;QACL,GAAG,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC;QAC9B,GAAG,KAAK,CAAC,GAAG;QACZ,GAAG,KAAK,CAAC,OAAO;QAChB,GAAG,KAAK,CAAC,IAAI;KACd,CAAC;AACJ,CAAC"}

package/dist/executors/event-parser.d.ts

@@ -0,0 +1,41 @@
+/** Result of parsing one complete line. */
+export type EventLineResult = {
+    kind: 'none';
+} | {
+    kind: 'event';
+    type: string;
+    data: Record<string, unknown>;
+} | {
+    kind: 'invalid';
+    error: string;
+};
+/** Parse one complete line (without the line terminator). */
+export declare function parseEventLine(line: string): EventLineResult;
+/** Callbacks of an {@link EventLineParser}. */
+export interface EventLineHandlers {
+    onEvent(type: string, data: Record<string, unknown>): void;
+    onInvalid(error: string, preview: string): void;
+}
+/**
+ * Incremental line splitter + event parser for one stream. Accepts decoded
+ * text in arbitrary chunks (lines may span chunks). Memory is bounded: a
+ * non-event line is not buffered beyond the prefix length, an event line is
+ * buffered up to the payload limit; longer event lines are discarded up to
+ * their newline and reported as invalid.
+ */
+export declare class EventLineParser {
+    private readonly handlers;
+    private buffer;
+    /** The current line is known not to be an event; skip until newline. */
+    private skipping;
+    /** The current event line exceeded the limit; skip until newline, then warn. */
+    private overflow;
+    private readonly maxLineChars;
+    constructor(handlers: EventLineHandlers);
+    /** Feed decoded text. */
+    push(text: string): void;
+    /** Process a final unterminated line (call at end of stream). */
+    flush(): void;
+    private append;
+    private completeLine;
+}

package/dist/executors/event-parser.js

@@ -0,0 +1,106 @@
+/**
+ * Line buffering and parsing of structured worker events (Spec §9.3).
+ *
+ * Lines starting with `@@ADISPATCH_EVENT ` carry a JSON object `{type: string, ...}`.
+ * Valid events are reported via callback; invalid event lines produce a
+ * parser warning. The raw line always stays in the log (this parser only
+ * observes the stream).
+ */
+import { MAX_EVENT_LINE_BYTES, ADISPATCH_EVENT_PREFIX, workerEventPayloadSchema } from '../core/index.js';
+/** Maximum length of the line preview included in parser warnings. */
+const PREVIEW_CHARS = 200;
+/** Parse one complete line (without the line terminator). */
+export function parseEventLine(line) {
+    if (!line.startsWith(ADISPATCH_EVENT_PREFIX))
+        return { kind: 'none' };
+    const payload = line.slice(ADISPATCH_EVENT_PREFIX.length);
+    if (Buffer.byteLength(payload, 'utf8') > MAX_EVENT_LINE_BYTES) {
+        return { kind: 'invalid', error: `event payload exceeds ${MAX_EVENT_LINE_BYTES} bytes` };
+    }
+    let json;
+    try {
+        json = JSON.parse(payload);
+    }
+    catch (err) {
+        return { kind: 'invalid', error: `event is not valid JSON: ${err.message}` };
+    }
+    const parsed = workerEventPayloadSchema.safeParse(json);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`).join('; ');
+        return { kind: 'invalid', error: `event does not match schema: ${issues}` };
+    }
+    return { kind: 'event', type: parsed.data.type, data: parsed.data };
+}
+/**
+ * Incremental line splitter + event parser for one stream. Accepts decoded
+ * text in arbitrary chunks (lines may span chunks). Memory is bounded: a
+ * non-event line is not buffered beyond the prefix length, an event line is
+ * buffered up to the payload limit; longer event lines are discarded up to
+ * their newline and reported as invalid.
+ */
+export class EventLineParser {
+    handlers;
+    buffer = '';
+    /** The current line is known not to be an event; skip until newline. */
+    skipping = false;
+    /** The current event line exceeded the limit; skip until newline, then warn. */
+    overflow = false;
+    maxLineChars = ADISPATCH_EVENT_PREFIX.length + MAX_EVENT_LINE_BYTES;
+    constructor(handlers) {
+        this.handlers = handlers;
+    }
+    /** Feed decoded text. */
+    push(text) {
+        let start = 0;
+        while (start < text.length) {
+            const nl = text.indexOf('\n', start);
+            const end = nl === -1 ? text.length : nl;
+            this.append(text.slice(start, end));
+            if (nl === -1)
+                break;
+            this.completeLine();
+            start = nl + 1;
+        }
+    }
+    /** Process a final unterminated line (call at end of stream). */
+    flush() {
+        if (this.buffer !== '' || this.overflow)
+            this.completeLine();
+        this.buffer = '';
+        this.skipping = false;
+        this.overflow = false;
+    }
+    append(part) {
+        if (this.skipping || this.overflow || part === '')
+            return;
+        this.buffer += part;
+        const prefixPart = this.buffer.slice(0, ADISPATCH_EVENT_PREFIX.length);
+        if (!ADISPATCH_EVENT_PREFIX.startsWith(prefixPart)) {
+            this.skipping = true;
+            this.buffer = '';
+            return;
+        }
+        // UTF-16 length is a lower bound of the UTF-8 byte length.
+        if (this.buffer.length > this.maxLineChars) {
+            this.overflow = true;
+            this.buffer = this.buffer.slice(0, PREVIEW_CHARS);
+        }
+    }
+    completeLine() {
+        if (this.overflow) {
+            this.handlers.onInvalid(`event payload exceeds ${MAX_EVENT_LINE_BYTES} bytes`, this.buffer.slice(0, PREVIEW_CHARS));
+        }
+        else if (!this.skipping && this.buffer !== '') {
+            const line = this.buffer.endsWith('\r') ? this.buffer.slice(0, -1) : this.buffer;
+            const result = parseEventLine(line);
+            if (result.kind === 'event')
+                this.handlers.onEvent(result.type, result.data);
+            else if (result.kind === 'invalid')
+                this.handlers.onInvalid(result.error, line.slice(0, PREVIEW_CHARS));
+        }
+        this.buffer = '';
+        this.skipping = false;
+        this.overflow = false;
+    }
+}
+//# sourceMappingURL=event-parser.js.map

package/dist/executors/event-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-parser.js","sourceRoot":"","sources":["../../src/executors/event-parser.ts"],"names":[],"mappings":"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"}

package/dist/executors/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Component `executors` – public API (WI-05): shell executor, worker
+ * protocol helpers, result classification and process start identity.
+ * Other components import from this module only.
+ */
+export { ShellExecutor, type ShellExecutorOptions } from './shell-executor.js';
+export { classifyOutcome } from './classify.js';
+export { checkProcessIdentity, createDarwinInspector, createLinuxInspector, defaultProcessInspector, getStartIdentity, isSameProcess, killProcessGroupIfSame, parseProcStat, parsePsOutput, processGroupAlive, processGroupExists, terminateProcessGroupIfSame, type TerminateOptions, type TerminateResult, type CommandRunner, type IdentityCheck, type KillFn, type KillIfSameResult, type ProcessInspector, type ProcessProbe, } from './process-identity.js';
+export { buildMinimalEnv, buildOrchEnv, contextSource, type OrchSourceInfo, buildWorkerEnv, FALLBACK_PATH, MINIMAL_ENV_KEYS } from './env.js';
+export { EventLineParser, parseEventLine, type EventLineHandlers, type EventLineResult } from './event-parser.js';
+export { ensureWorkspaceWithin } from './workspace.js';
+export { MIN_STREAM_SECRET_LENGTH, REDACTION_MARKER, StreamRedactor } from './stream-redactor.js';

package/dist/executors/index.js

@@ -0,0 +1,13 @@
+/**
+ * Component `executors` – public API (WI-05): shell executor, worker
+ * protocol helpers, result classification and process start identity.
+ * Other components import from this module only.
+ */
+export { ShellExecutor } from './shell-executor.js';
+export { classifyOutcome } from './classify.js';
+export { checkProcessIdentity, createDarwinInspector, createLinuxInspector, defaultProcessInspector, getStartIdentity, isSameProcess, killProcessGroupIfSame, parseProcStat, parsePsOutput, processGroupAlive, processGroupExists, terminateProcessGroupIfSame, } from './process-identity.js';
+export { buildMinimalEnv, buildOrchEnv, contextSource, buildWorkerEnv, FALLBACK_PATH, MINIMAL_ENV_KEYS } from './env.js';
+export { EventLineParser, parseEventLine } from './event-parser.js';
+export { ensureWorkspaceWithin } from './workspace.js';
+export { MIN_STREAM_SECRET_LENGTH, REDACTION_MARKER, StreamRedactor } from './stream-redactor.js';
+//# sourceMappingURL=index.js.map

package/dist/executors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/executors/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,aAAa,EAA6B,MAAM,qBAAqB,CAAC;AAC/E,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,uBAAuB,EACvB,gBAAgB,EAChB,aAAa,EACb,sBAAsB,EACtB,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,kBAAkB,EAClB,2BAA2B,GAS5B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,aAAa,EAAuB,cAAc,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC9I,OAAO,EAAE,eAAe,EAAE,cAAc,EAAgD,MAAM,mBAAmB,CAAC;AAClH,OAAO,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,wBAAwB,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/executors/log-capture.d.ts

@@ -0,0 +1,57 @@
+import type { Clock, ExecutorDiagnostic, OutputChunk } from '../core/index.js';
+import type { StreamRedactor } from './stream-redactor.js';
+/** Byte budget shared by all log streams of one run. */
+export declare class LogBudget {
+    readonly limit: number | undefined;
+    private used;
+    constructor(limit: number | undefined);
+    /** Reserve up to `bytes`; returns how many bytes may be written. */
+    take(bytes: number): number;
+}
+/** Sinks for everything a capture produces. */
+export interface CaptureSinks {
+    output(chunk: OutputChunk): void;
+    event(type: string, data: Record<string, unknown>, stream: 'stdout' | 'stderr'): void;
+    diagnostic(diagnostic: ExecutorDiagnostic): void;
+}
+export interface StreamCaptureOptions {
+    stream: 'stdout' | 'stderr';
+    /** Log file path; `undefined` disables file output (e.g. directory could not be created). */
+    filePath: string | undefined;
+    /** Error that prevented opening the file, reported as `log_write_error`. */
+    openError?: Error;
+    /** Shared per-run budget (default: unlimited). */
+    budget?: LogBudget;
+    redactor: StreamRedactor;
+    clock: Clock;
+    sinks: CaptureSinks;
+}
+export declare class StreamCapture {
+    private readonly opts;
+    private readonly stream;
+    private readonly decoder;
+    private readonly parser;
+    private readonly file;
+    private accepted;
+    private limitReached;
+    private writeFailed;
+    private drainWaiter;
+    private closed;
+    constructor(opts: StreamCaptureOptions);
+    /** Bytes handed to the log file (after redaction, within the limit). */
+    get bytesWritten(): number;
+    /** True if the persisted log is incomplete (size limit or write error). */
+    get truncated(): boolean;
+    /**
+     * Feed raw bytes. Returns `false` if the source should pause until
+     * `onDrain` is called (file buffer full).
+     */
+    push(raw: Buffer, onDrain: () => void): boolean;
+    /** Flush buffered data, close the file and wait until it is closed. */
+    end(): Promise<void>;
+    private handle;
+    private deliverText;
+    private writeFile;
+    private releaseDrain;
+    private fail;
+}

package/dist/executors/log-capture.js

@@ -0,0 +1,155 @@
+/**
+ * Capture of one output stream (stdout or stderr) of a worker (Spec §9.3, §5.1, §12):
+ * raw bytes → secret redaction → log file (size limit) + live output
+ * listeners + event line parser.
+ *
+ * - The log file receives the bytes unchanged except for redacted secrets.
+ * - The size limit is a per-run budget shared by stdout and stderr
+ *   ({@link LogBudget}, Spec §5.1 `max_log_size_per_run`). When a stream hits
+ *   it, that stream's file is not written any further and a single
+ *   `log_truncated` diagnostic naming the stream is emitted (no silent overwrite).
+ * - Write errors produce a `log_write_error` diagnostic; the log is then
+ *   reported as incomplete (`truncated`), never as complete.
+ * - Backpressure only comes from the file: {@link StreamCapture.push}
+ *   returns `false` when the file stream's buffer is full, and the caller
+ *   pauses the source until `onDrain`. Listeners never block (see Dispatcher).
+ */
+import { createWriteStream } from 'node:fs';
+import { StringDecoder } from 'node:string_decoder';
+import { EventLineParser } from './event-parser.js';
+/** Byte budget shared by all log streams of one run. */
+export class LogBudget {
+    limit;
+    used = 0;
+    constructor(limit) {
+        this.limit = limit;
+    }
+    /** Reserve up to `bytes`; returns how many bytes may be written. */
+    take(bytes) {
+        if (this.limit === undefined)
+            return bytes;
+        const granted = Math.max(0, Math.min(bytes, this.limit - this.used));
+        this.used += granted;
+        return granted;
+    }
+}
+export class StreamCapture {
+    opts;
+    stream;
+    decoder = new StringDecoder('utf8');
+    parser;
+    file;
+    accepted = 0;
+    limitReached = false;
+    writeFailed = false;
+    drainWaiter;
+    closed;
+    constructor(opts) {
+        this.opts = opts;
+        this.stream = opts.stream;
+        this.parser = new EventLineParser({
+            onEvent: (type, data) => opts.sinks.event(type, data, this.stream),
+            onInvalid: (error, preview) => opts.sinks.diagnostic({
+                type: 'event_parse_warning',
+                at: opts.clock.now(),
+                stream: this.stream,
+                message: `invalid worker event line: ${error}`,
+                details: { line: preview },
+            }),
+        });
+        if (opts.openError || opts.filePath === undefined) {
+            this.fail(opts.openError ?? new Error('log file unavailable'));
+            this.closed = Promise.resolve();
+            return;
+        }
+        const file = createWriteStream(opts.filePath, { flags: 'w', mode: 0o600 });
+        this.file = file;
+        this.closed = new Promise((resolve) => file.once('close', () => resolve()));
+        file.on('error', (err) => this.fail(err));
+    }
+    /** Bytes handed to the log file (after redaction, within the limit). */
+    get bytesWritten() {
+        return this.file ? Math.min(this.file.bytesWritten, this.accepted) : 0;
+    }
+    /** True if the persisted log is incomplete (size limit or write error). */
+    get truncated() {
+        return this.limitReached || this.writeFailed;
+    }
+    /**
+     * Feed raw bytes. Returns `false` if the source should pause until
+     * `onDrain` is called (file buffer full).
+     */
+    push(raw, onDrain) {
+        return this.handle(this.opts.redactor.push(raw), onDrain);
+    }
+    /** Flush buffered data, close the file and wait until it is closed. */
+    async end() {
+        this.handle(this.opts.redactor.flush(), () => { });
+        const tail = this.decoder.end();
+        if (tail)
+            this.deliverText(tail);
+        this.parser.flush();
+        if (this.file && !this.file.closed && !this.file.destroyed)
+            this.file.end();
+        await this.closed;
+    }
+    handle(data, onDrain) {
+        if (data.length === 0)
+            return true;
+        const text = this.decoder.write(data);
+        if (text)
+            this.deliverText(text);
+        return this.writeFile(data, onDrain);
+    }
+    deliverText(text) {
+        this.opts.sinks.output({ stream: this.stream, data: text, at: this.opts.clock.now() });
+        this.parser.push(text);
+    }
+    writeFile(data, onDrain) {
+        if (!this.file || this.writeFailed || this.limitReached)
+            return true;
+        let chunk = data;
+        const budget = this.opts.budget;
+        const granted = budget ? budget.take(chunk.length) : chunk.length;
+        if (granted < chunk.length) {
+            chunk = chunk.subarray(0, granted);
+            this.limitReached = true;
+            this.opts.sinks.diagnostic({
+                type: 'log_truncated',
+                at: this.opts.clock.now(),
+                stream: this.stream,
+                message: `run log limit of ${budget?.limit} bytes reached while writing ${this.stream}; further ${this.stream} output is not persisted`,
+                details: { limitBytes: budget?.limit, stream: this.stream },
+            });
+        }
+        if (chunk.length === 0)
+            return true;
+        this.accepted += chunk.length;
+        const ok = this.file.write(chunk);
+        if (ok)
+            return true;
+        this.drainWaiter = onDrain;
+        this.file.once('drain', () => this.releaseDrain());
+        return false;
+    }
+    releaseDrain() {
+        const waiter = this.drainWaiter;
+        this.drainWaiter = undefined;
+        waiter?.();
+    }
+    fail(err) {
+        if (this.writeFailed)
+            return;
+        this.writeFailed = true;
+        this.opts.sinks.diagnostic({
+            type: 'log_write_error',
+            at: this.opts.clock.now(),
+            stream: this.stream,
+            message: `${this.stream} log could not be written; the persisted log is incomplete: ${err.message}`,
+            details: { code: err.code, path: this.opts.filePath },
+        });
+        // 'drain' will never come after an error; do not leave the source paused.
+        this.releaseDrain();
+    }
+}
+//# sourceMappingURL=log-capture.js.map

package/dist/executors/log-capture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-capture.js","sourceRoot":"","sources":["../../src/executors/log-capture.ts"],"names":[],"mappings":"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"}

package/dist/executors/process-identity.d.ts

@@ -0,0 +1,124 @@
+import { type ProcessStartIdentity, type Timers } from '../core/index.js';
+/** Raw identity data of a live process. */
+export interface ProcessProbe {
+    pgid: number;
+    token: string;
+}
+/**
+ * Platform adapter. `probe` returns `null` if the process does not exist and
+ * throws if the state cannot be determined.
+ */
+export interface ProcessInspector {
+    readonly platform: string;
+    probe(pid: number): Promise<ProcessProbe | null>;
+    /**
+     * Optional precise check whether group `pgid` has members that are not
+     * zombies. Without it, a signal-0 probe is used (zombies count as alive).
+     */
+    groupHasLiveMembers?(pgid: number): Promise<boolean>;
+}
+/** Result of comparing a live process with a persisted identity. */
+export type IdentityCheck = 
+/** Same process (start token and process group match). */
+'same'
+/** A different process uses this PID now (PID reuse). */
+ | 'different'
+/** No process with this PID exists. */
+ | 'gone'
+/** Could not be determined (error, unsupported platform, changed group) — never signal. */
+ | 'unknown';
+/** Outcome of {@link killProcessGroupIfSame}. */
+export type KillIfSameResult = {
+    signalled: true;
+} | {
+    signalled: false;
+    reason: Exclude<IdentityCheck, 'same'> | 'pgid_mismatch' | 'signal_failed';
+    error?: string;
+};
+/**
+ * Parse the content of `/proc/<pid>/stat`. The command name (field 2) may
+ * contain spaces and parentheses, so fields are counted after the last `)`.
+ * Returns process group (field 5) and start time (field 22).
+ */
+export declare function parseProcStat(content: string): {
+    state: string;
+    pgrp: number;
+    starttime: string;
+};
+/** Linux implementation based on procfs. */
+export declare function createLinuxInspector(read?: (path: string) => Promise<string>, list?: (path: string) => Promise<string[]>): ProcessInspector;
+/** Parse the output of `ps -o pgid=,lstart= -p <pid>`. */
+export declare function parsePsOutput(output: string): ProcessProbe | null;
+/** Runs a command, resolving with exit code and stdout. */
+export type CommandRunner = (file: string, args: string[]) => Promise<{
+    code: number;
+    stdout: string;
+}>;
+/** macOS implementation based on `ps` (lstart = process start time). */
+export declare function createDarwinInspector(run?: CommandRunner): ProcessInspector;
+/** Inspector for the current platform; probing fails on unsupported platforms. */
+export declare function defaultProcessInspector(platform?: NodeJS.Platform): ProcessInspector;
+/**
+ * Capture the start identity of `pid`. Returns `undefined` if the process
+ * does not exist (anymore) or the identity cannot be determined.
+ */
+export declare function getStartIdentity(pid: number, inspector?: ProcessInspector): Promise<ProcessStartIdentity | undefined>;
+/** Compare the live process `identity.pid` with the persisted identity. */
+export declare function checkProcessIdentity(identity: ProcessStartIdentity, inspector?: ProcessInspector): Promise<IdentityCheck>;
+/** True only if `pid` is verifiably the process described by `identity`. */
+export declare function isSameProcess(pid: number, identity: ProcessStartIdentity, inspector?: ProcessInspector): Promise<boolean>;
+/** Signal sender, injectable for tests (default `process.kill`). */
+export type KillFn = (pid: number, signal: NodeJS.Signals | 0) => void;
+/**
+ * Send `signal` to process group `pgid`, but only if its leader
+ * (`identity.pid`) is verifiably the same process as recorded in `identity`
+ * (Spec §13). Never signals on doubt.
+ *
+ * Note: if the leader is gone while other group members still run, the group
+ * cannot be verified and is not signalled (reason `gone`); use
+ * {@link processGroupExists} to detect that case and report it.
+ */
+export declare function killProcessGroupIfSame(pgid: number, identity: ProcessStartIdentity, signal: NodeJS.Signals, deps?: {
+    inspector?: ProcessInspector;
+    kill?: KillFn;
+}): Promise<KillIfSameResult>;
+/** True if at least one process is in group `pgid` (signal 0 probe; EPERM counts as existing). */
+export declare function processGroupExists(pgid: number): boolean;
+/**
+ * True if group `pgid` still has live (non-zombie) members. Falls back to the
+ * signal-0 probe if the platform has no precise check or it fails.
+ */
+export declare function processGroupAlive(pgid: number, inspector?: ProcessInspector): Promise<boolean>;
+/** Outcome of {@link terminateProcessGroupIfSame}. */
+export type TerminateResult = 
+/** Identity verified, group signalled and confirmed gone. */
+'terminated'
+/** Identity verified and signalled, but the group is still alive after SIGKILL. */
+ | 'kill_failed'
+/** A different process uses the leader PID now; nothing signalled. */
+ | 'not_same'
+/** Leader and group are gone; nothing to do. */
+ | 'gone'
+/** Identity could not be determined (or pgid mismatch); nothing signalled. */
+ | 'unknown'
+/**
+ * The leader is gone but members of the group are still alive. They cannot
+ * be verified, so nothing is signalled — caller should set `recovery_pending`.
+ */
+ | 'group_alive_unverifiable';
+/** Options of {@link terminateProcessGroupIfSame}. */
+export interface TerminateOptions {
+    inspector?: ProcessInspector;
+    kill?: KillFn;
+    timers?: Timers;
+    /** Wait after SIGKILL before reporting `kill_failed`. Default 5 s. */
+    killConfirmMs?: number;
+    /** Poll interval while waiting for the group to vanish. Default 25 ms. */
+    pollIntervalMs?: number;
+}
+/**
+ * Recovery helper (Spec §13, §14 variant A): verify the start identity of the
+ * group leader, then SIGTERM the group, SIGKILL after `graceMs` and confirm
+ * that no live member remains. Never signals on doubt.
+ */
+export declare function terminateProcessGroupIfSame(identity: ProcessStartIdentity, graceMs: number, options?: TerminateOptions): Promise<TerminateResult>;