@namzu/sdk 38.2.1 → 40.0.0

package/dist/runtime/jobs/awaited-jobs.d.ts

@@ -0,0 +1,215 @@
+import type { BackgroundJob, BackgroundJobRegistry } from './registry.js';
+/**
+ * What this adapter needs from a registry: the jobs' exits, and one job's
+ * current status. Structural rather than the class, for the reason
+ * `BackgroundJobRegistryRef` is: the kernel passes the real registry, and a
+ * test that needs two exits and nothing else should not have to spawn
+ * processes to produce them.
+ */
+export type AwaitedJobSource = Pick<BackgroundJobRegistry, 'get' | 'onExit'>;
+/** Exits and the text that puts them in front of the model. See {@link AwaitedJobs.takeDelivery}. */
+export interface DeliverableJobExits {
+    /** The notice text, already queued by the exit that produced it. */
+    readonly text: string;
+    /** The exits that text accounts for, taken from the record. */
+    readonly exits: readonly BackgroundJob[];
+}
+/**
+ * Background jobs the model SAID it is waiting on.
+ *
+ * `CompletionInbox` gives a run a bounded, zero-token wait for a delegated
+ * task nobody is blocked on, and `holdForOutstandingWork` spends it: the
+ * model stops calling tools, the loop races the inbox against operator input,
+ * and the run only settles once the result is in the transcript or the grace
+ * is gone. Background shell jobs had none of it — so a model that started a
+ * job and then had nothing left to do improvised, and the recorded run
+ * (research/resident/results/2026-09-14-exploration-policy-terra-tui.json)
+ * shows what that costs: six `job read` polls, three `job list` polls and a
+ * `sleep 30`, each one a full context resend.
+ *
+ * This is the same three-method shape the hold already races —
+ * {@link hasPendingWork}, {@link waitForArrival}, {@link drain} — over the
+ * job registry instead of the task gateway.
+ *
+ * **Intent is stated, never inferred.** A job is only outstanding here once
+ * `wait_for_job` named it (see {@link expect}); job existence means nothing.
+ * That is the same distinction `CompletionInbox.expect` draws for a
+ * background task, and it is what keeps a dev server or a file watcher —
+ * started precisely so it would keep running — from holding every run of the
+ * session open for its grace period. The model that wants to wait says so.
+ */
+export declare class AwaitedJobs {
+    private readonly source;
+    /** Whose jobs these are — the run or the session the jobs are bound to. */
+    private readonly owner;
+    /**
+     * Whether the exit notice this run queues for the model is still
+     * unread. A second opinion on {@link noticesDelivered}, and it can
+     * only ever narrow what counts as pending.
+     *
+     * An exit is work only until the model has seen it, and this adapter is
+     * not what shows it: the text rides out on the next tool result
+     * (`attachNotice`), which is what normally happens, long before any
+     * hold opens. {@link noticesDelivered} is how that delivery says so,
+     * and it is the per-job record — the entry goes, so nothing can count
+     * it again.
+     *
+     * This stays because the two answer different questions. That one is
+     * reported BY a delivery site, so it is only as good as the sites that
+     * remember to call it; this reads the channel itself, and a channel
+     * with nothing queued cannot have news in it whatever the record says.
+     * It is also safe in one direction only: it can suppress a hold, never
+     * open one, so a stale `true` here is not a turn the model gets to
+     * spend — which is the failure this pair exists to prevent.
+     *
+     * `CompletionInbox.claim` draws the same line on the task side. It can
+     * name the task, because the call that delivers a completion knows
+     * which one it delivered; a notice is text by the time it reaches the
+     * tool result, so this asks the channel instead.
+     *
+     * Absent means nothing else consumes the notices, so a recorded exit is
+     * unread by definition.
+     */
+    private readonly unreadNotice?;
+    /** Awaited and still running. Nothing else can hold a run open. */
+    private readonly outstanding;
+    /** Exits since the last {@link drain}. */
+    private exits;
+    private readonly arrivals;
+    private detach?;
+    constructor(source: AwaitedJobSource, 
+    /** Whose jobs these are — the run or the session the jobs are bound to. */
+    owner: string, 
+    /**
+     * Whether the exit notice this run queues for the model is still
+     * unread. A second opinion on {@link noticesDelivered}, and it can
+     * only ever narrow what counts as pending.
+     *
+     * An exit is work only until the model has seen it, and this adapter is
+     * not what shows it: the text rides out on the next tool result
+     * (`attachNotice`), which is what normally happens, long before any
+     * hold opens. {@link noticesDelivered} is how that delivery says so,
+     * and it is the per-job record — the entry goes, so nothing can count
+     * it again.
+     *
+     * This stays because the two answer different questions. That one is
+     * reported BY a delivery site, so it is only as good as the sites that
+     * remember to call it; this reads the channel itself, and a channel
+     * with nothing queued cannot have news in it whatever the record says.
+     * It is also safe in one direction only: it can suppress a hold, never
+     * open one, so a stale `true` here is not a turn the model gets to
+     * spend — which is the failure this pair exists to prevent.
+     *
+     * `CompletionInbox.claim` draws the same line on the task side. It can
+     * name the task, because the call that delivers a completion knows
+     * which one it delivered; a notice is text by the time it reaches the
+     * tool result, so this asks the channel instead.
+     *
+     * Absent means nothing else consumes the notices, so a recorded exit is
+     * unread by definition.
+     */
+    unreadNotice?: (() => boolean) | undefined);
+    /**
+     * Start listening.
+     *
+     * Returns the detach, and attaching twice is a no-op rather than a second
+     * subscription — the same rule `CompletionInbox.attach` follows, for the
+     * same reason: two subscriptions would record each exit twice.
+     */
+    attach(): () => void;
+    /**
+     * Say that the model is waiting on this job's exit.
+     *
+     * Called by `wait_for_job`, and by nothing else: the wait is the whole
+     * signal. A job that has ALREADY stopped is not recorded, because the
+     * call that marks it is the same call that returns its output — holding
+     * the run open afterwards would buy a turn to read a result the model has
+     * just read. `CompletionInbox.expect` skips an already-claimed task for
+     * the same reason.
+     *
+     * An id the registry does not know is ignored rather than raised: the
+     * caller is about to fail on it anyway, and a marking call is not the
+     * place that decides what an unknown job means.
+     */
+    expect(id: string): void;
+    /**
+     * Recorded exits the model has not been shown yet.
+     *
+     * Both halves of the same question: {@link noticesDelivered} drops the
+     * entry when its notice goes out, and the `unreadNotice` constructor
+     * argument asks the channel whether anything is still queued. A queued
+     * exit whose notice has already been delivered is history, not pending
+     * work, and an exit nobody awaited is not this adapter's news to carry.
+     */
+    private get unreadExits();
+    /** Whether an awaited job is still running, or one has exited unread. */
+    get hasPendingWork(): boolean;
+    /**
+     * Wait for the next awaited job's exit, deadline or abort, whichever comes
+     * first. Aborting releases only this waiter; the jobs are untouched.
+     *
+     * Bounded by the caller, exactly as `CompletionInbox.waitForArrival` is: a
+     * job that never exits — a dev server someone did await — must not keep a
+     * run open, and only the run's own budget knows how long is long enough.
+     */
+    waitForArrival(timeoutMs: number, signal?: AbortSignal): Promise<void>;
+    /**
+     * Say that the queued exit notices have been put in front of the model.
+     *
+     * Called by the tool-result delivery (`attachNotice`), which is where an
+     * exit normally reaches the model; {@link takeDelivery} does the same for
+     * the hold's own path by taking the entries as it delivers them.
+     *
+     * Every recorded exit goes, and that is per-job rather than a blunt
+     * clear: the channel hands over ALL its queued text at once, and an exit
+     * is recorded here in the same synchronous announcement that queues its
+     * notice, so the text just delivered is exactly the notices of the exits
+     * in hand. An exit recorded after this call keeps its entry, because its
+     * notice was queued after that text was taken.
+     *
+     * Without it the entry outlived the delivery, and the channel-level gate
+     * above was the only thing standing between a read exit and a model turn
+     * — a gate that reopens the moment ANY later job, awaited or not, queues
+     * a notice of its own.
+     */
+    noticesDelivered(): void;
+    /**
+     * Take the recorded exits together with the text that delivers them, or
+     * take neither.
+     *
+     * The pairing is the whole method. Draining the exits first and then
+     * asking for the notice loses them on the branch that finds none: the
+     * records are gone, no text was written, and the exit the run held itself
+     * open for is delivered by nobody. So {@link drain} is not called until
+     * the delivery is certain, and an exit this could not deliver stays in
+     * hand for the next one.
+     */
+    takeDelivery(notice: () => string | undefined): DeliverableJobExits | undefined;
+    /**
+     * Take every exit recorded since the last call, leaving none behind.
+     *
+     * Draining rather than peeking, for the reason `CompletionInbox.drain`
+     * gives: an exit that stays queued after being delivered is a duplicate
+     * waiting to happen. Callers that are delivering want
+     * {@link takeDelivery}, which will not take them without the notice that
+     * accounts for them.
+     */
+    drain(): readonly BackgroundJob[];
+    /**
+     * Awaited jobs still running.
+     *
+     * Read when a run ends, so it can say which wait it walked away from.
+     * Nothing here is stopped by being read — the ids are a statement, and a
+     * job's lifetime belongs to whoever owns it.
+     */
+    get outstandingJobIds(): readonly string[];
+    /**
+     * Stop listening. Safe to call more than once.
+     *
+     * A run that ends without this leaves its listener on a registry the host
+     * reuses across runs — the leak `CompletionInbox.close` exists to prevent,
+     * on the other subsystem.
+     */
+    close(): void;
+}
+//# sourceMappingURL=awaited-jobs.d.ts.map

package/dist/runtime/jobs/awaited-jobs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"awaited-jobs.d.ts","sourceRoot":"","sources":["../../../src/runtime/jobs/awaited-jobs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAA;AAEzE;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,IAAI,CAAC,qBAAqB,EAAE,KAAK,GAAG,QAAQ,CAAC,CAAA;AAE5E,qGAAqG;AACrG,MAAM,WAAW,mBAAmB;IACnC,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAA;CACxC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,WAAW;IAStB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,2EAA2E;IAC3E,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC;IAvC/B,mEAAmE;IACnE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;IAChD,0CAA0C;IAC1C,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAwB;IACjD,OAAO,CAAC,MAAM,CAAC,CAAY;gBAGT,MAAM,EAAE,gBAAgB;IACzC,2EAA2E;IAC1D,KAAK,EAAE,MAAM;IAC9B;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACc,YAAY,CAAC,GAAE,MAAM,OAAO,aAAA;IAG9C;;;;;;OAMG;IACH,MAAM,IAAI,MAAM,IAAI;IAgBpB;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAYxB;;;;;;;;OAQG;IACH,OAAO,KAAK,WAAW,GAGtB;IAED,yEAAyE;IACzE,IAAI,cAAc,IAAI,OAAO,CAE5B;IAED;;;;;;;OAOG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBtE;;;;;;;;;;;;;;;;;;OAkBG;IACH,gBAAgB,IAAI,IAAI;IAIxB;;;;;;;;;;OAUG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,MAAM,GAAG,SAAS,GAAG,mBAAmB,GAAG,SAAS;IAO/E;;;;;;;;OAQG;IACH,KAAK,IAAI,SAAS,aAAa,EAAE;IAOjC;;;;;;OAMG;IACH,IAAI,iBAAiB,IAAI,SAAS,MAAM,EAAE,CAEzC;IAED;;;;;;OAMG;IACH,KAAK,IAAI,IAAI;CAUb"}

package/dist/runtime/jobs/awaited-jobs.js

@@ -0,0 +1,259 @@
+/**
+ * Background jobs the model SAID it is waiting on.
+ *
+ * `CompletionInbox` gives a run a bounded, zero-token wait for a delegated
+ * task nobody is blocked on, and `holdForOutstandingWork` spends it: the
+ * model stops calling tools, the loop races the inbox against operator input,
+ * and the run only settles once the result is in the transcript or the grace
+ * is gone. Background shell jobs had none of it — so a model that started a
+ * job and then had nothing left to do improvised, and the recorded run
+ * (research/resident/results/2026-09-14-exploration-policy-terra-tui.json)
+ * shows what that costs: six `job read` polls, three `job list` polls and a
+ * `sleep 30`, each one a full context resend.
+ *
+ * This is the same three-method shape the hold already races —
+ * {@link hasPendingWork}, {@link waitForArrival}, {@link drain} — over the
+ * job registry instead of the task gateway.
+ *
+ * **Intent is stated, never inferred.** A job is only outstanding here once
+ * `wait_for_job` named it (see {@link expect}); job existence means nothing.
+ * That is the same distinction `CompletionInbox.expect` draws for a
+ * background task, and it is what keeps a dev server or a file watcher —
+ * started precisely so it would keep running — from holding every run of the
+ * session open for its grace period. The model that wants to wait says so.
+ */
+export class AwaitedJobs {
+    source;
+    owner;
+    unreadNotice;
+    /** Awaited and still running. Nothing else can hold a run open. */
+    outstanding = new Set();
+    /** Exits since the last {@link drain}. */
+    exits = [];
+    arrivals = new Set();
+    detach;
+    constructor(source, 
+    /** Whose jobs these are — the run or the session the jobs are bound to. */
+    owner, 
+    /**
+     * Whether the exit notice this run queues for the model is still
+     * unread. A second opinion on {@link noticesDelivered}, and it can
+     * only ever narrow what counts as pending.
+     *
+     * An exit is work only until the model has seen it, and this adapter is
+     * not what shows it: the text rides out on the next tool result
+     * (`attachNotice`), which is what normally happens, long before any
+     * hold opens. {@link noticesDelivered} is how that delivery says so,
+     * and it is the per-job record — the entry goes, so nothing can count
+     * it again.
+     *
+     * This stays because the two answer different questions. That one is
+     * reported BY a delivery site, so it is only as good as the sites that
+     * remember to call it; this reads the channel itself, and a channel
+     * with nothing queued cannot have news in it whatever the record says.
+     * It is also safe in one direction only: it can suppress a hold, never
+     * open one, so a stale `true` here is not a turn the model gets to
+     * spend — which is the failure this pair exists to prevent.
+     *
+     * `CompletionInbox.claim` draws the same line on the task side. It can
+     * name the task, because the call that delivers a completion knows
+     * which one it delivered; a notice is text by the time it reaches the
+     * tool result, so this asks the channel instead.
+     *
+     * Absent means nothing else consumes the notices, so a recorded exit is
+     * unread by definition.
+     */
+    unreadNotice) {
+        this.source = source;
+        this.owner = owner;
+        this.unreadNotice = unreadNotice;
+    }
+    /**
+     * Start listening.
+     *
+     * Returns the detach, and attaching twice is a no-op rather than a second
+     * subscription — the same rule `CompletionInbox.attach` follows, for the
+     * same reason: two subscriptions would record each exit twice.
+     */
+    attach() {
+        if (this.detach)
+            return this.detach;
+        this.detach = this.source.onExit((job) => {
+            // `onExit` is a broadcast over a registry a host may share between
+            // runs, and the filter is the same one the exit-notice channel
+            // applies in `runtime/query/index.ts`.
+            if (job.owner !== this.owner)
+                return;
+            // `outstanding` is the gate, so an id nobody awaited is ignored and
+            // a second announcement for the same job cannot queue twice.
+            if (!this.outstanding.delete(job.id))
+                return;
+            this.exits.push(job);
+            for (const wake of [...this.arrivals])
+                wake();
+        });
+        return this.detach;
+    }
+    /**
+     * Say that the model is waiting on this job's exit.
+     *
+     * Called by `wait_for_job`, and by nothing else: the wait is the whole
+     * signal. A job that has ALREADY stopped is not recorded, because the
+     * call that marks it is the same call that returns its output — holding
+     * the run open afterwards would buy a turn to read a result the model has
+     * just read. `CompletionInbox.expect` skips an already-claimed task for
+     * the same reason.
+     *
+     * An id the registry does not know is ignored rather than raised: the
+     * caller is about to fail on it anyway, and a marking call is not the
+     * place that decides what an unknown job means.
+     */
+    expect(id) {
+        let job;
+        try {
+            job = this.source.get(id);
+        }
+        catch {
+            return;
+        }
+        if (job.owner !== this.owner)
+            return;
+        if (job.status !== 'running')
+            return;
+        this.outstanding.add(id);
+    }
+    /**
+     * Recorded exits the model has not been shown yet.
+     *
+     * Both halves of the same question: {@link noticesDelivered} drops the
+     * entry when its notice goes out, and the `unreadNotice` constructor
+     * argument asks the channel whether anything is still queued. A queued
+     * exit whose notice has already been delivered is history, not pending
+     * work, and an exit nobody awaited is not this adapter's news to carry.
+     */
+    get unreadExits() {
+        if (this.exits.length === 0)
+            return false;
+        return this.unreadNotice?.() ?? true;
+    }
+    /** Whether an awaited job is still running, or one has exited unread. */
+    get hasPendingWork() {
+        return this.unreadExits || this.outstanding.size > 0;
+    }
+    /**
+     * Wait for the next awaited job's exit, deadline or abort, whichever comes
+     * first. Aborting releases only this waiter; the jobs are untouched.
+     *
+     * Bounded by the caller, exactly as `CompletionInbox.waitForArrival` is: a
+     * job that never exits — a dev server someone did await — must not keep a
+     * run open, and only the run's own budget knows how long is long enough.
+     */
+    waitForArrival(timeoutMs, signal) {
+        if (signal?.aborted)
+            return Promise.resolve();
+        if (this.unreadExits)
+            return Promise.resolve();
+        if (this.outstanding.size === 0)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            const finish = () => {
+                clearTimeout(timer);
+                this.arrivals.delete(finish);
+                signal?.removeEventListener('abort', finish);
+                resolve();
+            };
+            const timer = setTimeout(finish, timeoutMs);
+            timer.unref?.();
+            this.arrivals.add(finish);
+            signal?.addEventListener('abort', finish, { once: true });
+            if (signal?.aborted)
+                finish();
+        });
+    }
+    /**
+     * Say that the queued exit notices have been put in front of the model.
+     *
+     * Called by the tool-result delivery (`attachNotice`), which is where an
+     * exit normally reaches the model; {@link takeDelivery} does the same for
+     * the hold's own path by taking the entries as it delivers them.
+     *
+     * Every recorded exit goes, and that is per-job rather than a blunt
+     * clear: the channel hands over ALL its queued text at once, and an exit
+     * is recorded here in the same synchronous announcement that queues its
+     * notice, so the text just delivered is exactly the notices of the exits
+     * in hand. An exit recorded after this call keeps its entry, because its
+     * notice was queued after that text was taken.
+     *
+     * Without it the entry outlived the delivery, and the channel-level gate
+     * above was the only thing standing between a read exit and a model turn
+     * — a gate that reopens the moment ANY later job, awaited or not, queues
+     * a notice of its own.
+     */
+    noticesDelivered() {
+        this.exits = [];
+    }
+    /**
+     * Take the recorded exits together with the text that delivers them, or
+     * take neither.
+     *
+     * The pairing is the whole method. Draining the exits first and then
+     * asking for the notice loses them on the branch that finds none: the
+     * records are gone, no text was written, and the exit the run held itself
+     * open for is delivered by nobody. So {@link drain} is not called until
+     * the delivery is certain, and an exit this could not deliver stays in
+     * hand for the next one.
+     */
+    takeDelivery(notice) {
+        if (this.exits.length === 0)
+            return undefined;
+        const text = notice();
+        if (text === undefined)
+            return undefined;
+        return { text, exits: this.drain() };
+    }
+    /**
+     * Take every exit recorded since the last call, leaving none behind.
+     *
+     * Draining rather than peeking, for the reason `CompletionInbox.drain`
+     * gives: an exit that stays queued after being delivered is a duplicate
+     * waiting to happen. Callers that are delivering want
+     * {@link takeDelivery}, which will not take them without the notice that
+     * accounts for them.
+     */
+    drain() {
+        if (this.exits.length === 0)
+            return [];
+        const exits = this.exits;
+        this.exits = [];
+        return exits;
+    }
+    /**
+     * Awaited jobs still running.
+     *
+     * Read when a run ends, so it can say which wait it walked away from.
+     * Nothing here is stopped by being read — the ids are a statement, and a
+     * job's lifetime belongs to whoever owns it.
+     */
+    get outstandingJobIds() {
+        return [...this.outstanding];
+    }
+    /**
+     * Stop listening. Safe to call more than once.
+     *
+     * A run that ends without this leaves its listener on a registry the host
+     * reuses across runs — the leak `CompletionInbox.close` exists to prevent,
+     * on the other subsystem.
+     */
+    close() {
+        this.detach?.();
+        this.detach = undefined;
+        this.outstanding.clear();
+        this.exits = [];
+        // Release anyone still waiting. A closed adapter would otherwise hold
+        // them to their own deadline for an exit that can no longer reach them.
+        for (const wake of [...this.arrivals])
+            wake();
+        this.arrivals.clear();
+    }
+}
+//# sourceMappingURL=awaited-jobs.js.map

package/dist/runtime/jobs/awaited-jobs.js.map

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

package/dist/runtime/jobs/registry.d.ts

@@ -119,6 +119,22 @@ export declare class BackgroundJobRegistry {
     start(params: StartJobParams): BackgroundJob;
     /** The record, or throw for an id this registry does not know. */
     get(id: string): BackgroundJob;
+    /**
+     * Await one job's exit — the public counterpart to `onExit`, for a
+     * caller that wants a single result rather than a standing
+     * subscription. Resolves at once for a job that has already stopped, so
+     * a caller that lost the race against a fast-finishing job never blocks
+     * on a promise that would otherwise never settle.
+     *
+     * `signal` is honoured: an aborted wait rejects and detaches rather than
+     * holding the internal exit promise's continuation open for a job that
+     * may run for another hour. That only ends the WAIT — the job itself is
+     * untouched either way, exactly as a timed-out `kill`-less wait leaves
+     * it. See `wait-for-job-bounds.ts`, the first caller.
+     */
+    waitForExit(id: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<BackgroundJob>;
     /**
      * Output since `fromOffset`, with what the cap dropped stated.
      *
@@ -161,7 +177,21 @@ export declare function bindOwner(registry: BackgroundJobRegistry, owner: string
         readonly workingDirectory: string;
         readonly env?: Record<string, string>;
     }) => JobProcess;
+    /**
+     * Be told that the model said it is waiting on a job's exit.
+     *
+     * The registry does not keep this: wait-intent belongs to the RUN that
+     * expressed it, not to a registry a host may share across runs and
+     * sessions. The run passes its own recorder here — `AwaitedJobs`, which
+     * is what the iteration loop holds open for. Absent means nobody is
+     * listening, and `markAwaited` is then absent from the bound ref rather
+     * than present and silently doing nothing.
+     */
+    readonly onAwaited?: (id: string) => void;
 }): {
+    kill: (id: string) => Promise<BackgroundJob>;
+    list: () => readonly BackgroundJob[];
+    markAwaited?: ((id: string) => void) | undefined;
     start: (params: {
         command: string;
         workingDirectory?: string;
@@ -170,7 +200,8 @@ export declare function bindOwner(registry: BackgroundJobRegistry, owner: string
     read: (id: string, opts?: {
         fromOffset?: number;
     }) => BackgroundJobOutput;
-    kill: (id: string) => Promise<BackgroundJob>;
-    list: () => readonly BackgroundJob[];
+    waitForExit: (id: string, opts?: {
+        signal?: AbortSignal;
+    }) => Promise<BackgroundJob>;
 };
 //# sourceMappingURL=registry.d.ts.map

package/dist/runtime/jobs/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/runtime/jobs/registry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/runtime/jobs/registry.ts"],"names":[],"mappings":"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"}

package/dist/runtime/jobs/registry.js

@@ -2,6 +2,7 @@ import { spawn } from 'node:child_process';
 import { SANDBOX_KILL_GRACE_MS } from '../../constants/sandbox/index.js';
 import { killTree } from '../../process/kill-tree.js';
 import { scrubInheritedEnv } from '../../tools/env-scrub.js';
+import { awaitWithAbort } from '../../utils/await-with-abort.js';
 const DEFAULT_MAX_JOBS_PER_OWNER = 8;
 const DEFAULT_MAX_OUTPUT_BYTES = 1024 * 1024;
 /** A start that would exceed a declared bound. */
@@ -195,6 +196,30 @@ export class BackgroundJobRegistry {
             throw new UnknownBackgroundJobError({ id });
         return entry.record;
     }
+    /**
+     * Await one job's exit — the public counterpart to `onExit`, for a
+     * caller that wants a single result rather than a standing
+     * subscription. Resolves at once for a job that has already stopped, so
+     * a caller that lost the race against a fast-finishing job never blocks
+     * on a promise that would otherwise never settle.
+     *
+     * `signal` is honoured: an aborted wait rejects and detaches rather than
+     * holding the internal exit promise's continuation open for a job that
+     * may run for another hour. That only ends the WAIT — the job itself is
+     * untouched either way, exactly as a timed-out `kill`-less wait leaves
+     * it. See `wait-for-job-bounds.ts`, the first caller.
+     */
+    waitForExit(id, opts = {}) {
+        const entry = this.jobs.get(id);
+        if (!entry)
+            throw new UnknownBackgroundJobError({ id });
+        if (entry.record.status !== 'running')
+            return Promise.resolve(entry.record);
+        // `entry` is the same object the `finalize` closure in `start()`
+        // mutates in place, so reading `entry.record` after `exit` settles
+        // sees the final status — the same trick `kill()` already relies on.
+        return awaitWithAbort(entry.exit.then(() => entry.record), opts.signal);
+    }
     /**
      * Output since `fromOffset`, with what the cap dropped stated.
      *
@@ -312,6 +337,18 @@ export function bindOwner(registry, owner, defaults = {}) {
             mine(id);
             return registry.read(id, opts ?? {});
         },
+        waitForExit: (id, opts) => {
+            mine(id);
+            return registry.waitForExit(id, opts ?? {});
+        },
+        ...(defaults.onAwaited
+            ? {
+                markAwaited: (id) => {
+                    mine(id);
+                    defaults.onAwaited?.(id);
+                },
+            }
+            : {}),
         kill: async (id) => {
             mine(id);
             return await registry.kill(id);