@pentoshi/clai 3.9.1 → 3.9.3

package/dist/tools/jobs.d.ts

@@ -14,6 +14,12 @@ export type JobMonitorMetadata = Record<string, unknown>;
 export interface JobLinkMetadata {
     taskId?: string | undefined;
     parentTaskId?: string | undefined;
+    /**
+     * Stable delegation identity minted before launch. It is the
+     * reconciliation key between a job and its responder child task, so a fast
+     * exit or a failed link cannot orphan the child.
+     */
+    delegationId?: string | undefined;
     wakeOnCompletion?: boolean | undefined;
     monitor?: JobMonitorMetadata | undefined;
     /** Runtime listening lease that authorized this responder delegation. */
@@ -65,6 +71,19 @@ export interface BackgroundJob extends JobLinkMetadata {
     timeoutAt?: string | undefined;
 }
 export declare function formatJobElapsed(job: Pick<BackgroundJob, "startedAt" | "endedAt">, now?: number): string;
+export interface SupersededResultRevision {
+    resultRevision: number;
+    resultHash: string;
+    status: JobTerminalStatus;
+    endedAt: string;
+    exitCode?: number | undefined;
+    signal?: string | undefined;
+    deliveredAt?: string | undefined;
+    readAt?: string | undefined;
+    analyzedAt?: string | undefined;
+    acknowledgedAt?: string | undefined;
+    settledAt?: string | undefined;
+}
 export interface ResponderNotification {
     id: string;
     ownerSessionId: string;
@@ -84,10 +103,21 @@ export interface ResponderNotification {
     responder: boolean;
     monitor?: JobMonitorMetadata | undefined;
     responderLeaseId?: string | undefined;
+    /** A delivery attempt began; not durable consumption. Cleared claims may retry. */
+    deliveryStartedAt?: string | undefined;
     deliveredAt?: string | undefined;
     readAt?: string | undefined;
     analyzedAt?: string | undefined;
     acknowledgedAt?: string | undefined;
+    /** User discarded this receipt (cancel/new session); never model analysis. */
+    discardedAt?: string | undefined;
+    discardReason?: "session-cancelled" | undefined;
+    /** Monotonic revision of the authoritative result this receipt carries. */
+    resultRevision?: number | undefined;
+    /** Content hash of the authoritative result, used to detect a correction. */
+    resultHash?: string | undefined;
+    /** Bounded audit trail of revisions this receipt superseded. */
+    supersededRevisions?: readonly SupersededResultRevision[] | undefined;
     archivedAt?: string | undefined;
     settledAt?: string | undefined;
 }
@@ -100,6 +130,16 @@ export type JobManagerChange = {
     notificationId: string;
 };
 export type JobManagerListener = (change: JobManagerChange) => void;
+/** Durable projection marker for a terminal result whose plan child is unsettled. */
+export interface PendingSettlement {
+    jobId: string;
+    resultRevision: number;
+    attempts: number;
+    firstAttemptAt: string;
+    lastAttemptAt: string;
+    lastReason: string;
+    deadLetteredAt?: string | undefined;
+}
 interface TailCursor {
     stream?: "stdout" | "stderr" | "combined";
     offset?: number;
@@ -137,7 +177,9 @@ export declare class JobManager {
     private authorizationTimers;
     private responderLeases;
     private settlementTimers;
-    private settlementAttempts;
+    private pendingSettlements;
+    private consumedResponderResults;
+    private livenessWatchTimer;
     private finalizations;
     private listeners;
     /**
@@ -147,11 +189,19 @@ export declare class JobManager {
      * observed alive again or finalized.
      */
     private livenessMisses;
+    private livenessCheckedAt;
     private registryRetryTimer;
     private readonly registryPath;
     private readonly transientV2RegistryPath;
     constructor(jobsDir?: string);
     private isDurable;
+    private artifactPathsOf;
+    /** Delete a dropped job's artifact chunks, never one still referenced. */
+    private removeJobArtifacts;
+    /** Drop a job row plus its per-job caches and artifacts. */
+    private forgetJob;
+    /** Remove artifact files whose job row no longer exists. */
+    private sweepOrphanArtifacts;
     private isLive;
     private isTerminalStatus;
     private emit;
@@ -170,6 +220,25 @@ export declare class JobManager {
     /** Reconcile a restored process that no longer has a ChildProcess close event. */
     private refreshJobLiveness;
     private scheduleTaskSettlement;
+    private completeSettlement;
+    /**
+     * Retry until the projection lands. The marker is durable, so a crash or a
+     * long-lived plan-write conflict cannot silently strand a green child, and an
+     * unrecoverable case is dead-lettered with a visible reason.
+     */
+    private retrySettlement;
+    /**
+     * One coalesced, unref'd watcher that reconciles restored live jobs without a
+     * UI read. Without it a headless session can leave a finished responder job
+     * "running" forever, because liveness was only refreshed by list/get calls.
+     */
+    private scheduleLivenessWatch;
+    /** Ownership guard: a receipt may only be mutated by its owning session. */
+    private ownsNotification;
+    /** Receipt for a launch that was deduplicated by its delegation key. */
+    private startJobReceipt;
+    /** Terminal results whose plan child could not be settled yet. */
+    getPendingSettlements(): PendingSettlement[];
     /**
      * Register an in-flight tool for stall tracking only.
      * Never appears in shell.jobs and never touches the durable registry.
@@ -188,10 +257,15 @@ export declare class JobManager {
     pendingNotifications(sessionId?: string): ResponderNotification[];
     claimNextResponderNotification(sessionId: string, leaseId: string): ResponderNotification | undefined;
     releaseResponderNotificationClaim(notificationId: string): void;
-    markDelivered(notificationId: string): boolean;
+    /**
+     * Record that a delivery attempt started. This is deliberately weaker than
+     * `markDelivered`: an aborted or failed analysis turn must remain deliverable.
+     */
+    markDeliveryStarted(notificationId: string, sessionId?: string): boolean;
+    markDelivered(notificationId: string, sessionId?: string): boolean;
     markRead(notificationId: string, sessionId: string): boolean;
-    markAnalyzed(notificationId: string): boolean;
-    acknowledge(notificationId: string): boolean;
+    markAnalyzed(notificationId: string, sessionId?: string): boolean;
+    acknowledge(notificationId: string, sessionId?: string): boolean;
     linkJob(jobId: string, metadata: JobLinkMetadata): BackgroundJob | undefined;
     tailJob(id: string, bytesOrCursor?: number | TailCursor): Promise<ToolResult>;
     stopJob(id: string, options?: {