@skrr-ai/cli 0.1.118 → 0.1.120

package/dist/lib/task-asset-upload.js

@@ -37,6 +37,8 @@ exports.readTaskForUpload = readTaskForUpload;
 exports.uploadTaskAssetFile = uploadTaskAssetFile;
 exports.attachTaskAssetFiles = attachTaskAssetFiles;
 exports.taskAssetMarkdownRef = taskAssetMarkdownRef;
+exports.taskAssetUploadRecovery = taskAssetUploadRecovery;
+exports.putFilePartToStorage = putFilePartToStorage;
 exports.sha256OfFile = sha256OfFile;
 exports.postFileToStorage = postFileToStorage;
 /**
@@ -45,7 +47,7 @@ exports.postFileToStorage = postFileToStorage;
  * funnel here so the routing rules live in exactly one place (OSK-9863).
  *
  *   ≤25MB or image → buffered multipart (canonicalization needs the bytes)
- *   larger non-image → intent → presigned POST to S3 → complete (OSK-9867)
+ *   larger non-image → intent → granted single/multipart transport → complete
  *
  * Agent uploads retain the authenticated session producer even beside a wide
  * delegated credential. Human uploads use `/api/tasks/:id/*`.
@@ -100,6 +102,11 @@ async function readTaskForUpload(taskId) {
  */
 async function uploadTaskAssetFile(opts) {
     const { taskId, filePath, role, ledger } = opts;
+    if (opts.resumeAttachmentId !== undefined &&
+        (!opts.resumeAttachmentId || opts.resumeAttachmentId.trim() !== opts.resumeAttachmentId ||
+            opts.resumeAttachmentId.length > 200 || ledger !== undefined)) {
+        throw new Error('Resume requires one exact attachment id and retains its original ledger declaration.');
+    }
     if (!fs.existsSync(filePath)) {
         throw new Error(`File not found: ${filePath}`);
     }
@@ -121,7 +128,11 @@ async function uploadTaskAssetFile(opts) {
     const sessionTarget = await (0, session_task_write_1.sessionTaskWrite)('attachment', taskId);
     let result;
     try {
-        if (sessionTarget) {
+        if (opts.resumeAttachmentId !== undefined) {
+            result = await resumeDirectUpload({ taskId, filePath, size, filename, mimeType, role,
+                attachmentId: opts.resumeAttachmentId }, sessionTarget);
+        }
+        else if (sessionTarget) {
             result = direct
                 ? await sessionDirectUpload({ filePath, size, filename, mimeType, role, ledger }, sessionTarget)
                 : await sessionBufferedUpload({ filePath, filename, mimeType, role, ledger }, sessionTarget);
@@ -135,7 +146,9 @@ async function uploadTaskAssetFile(opts) {
     catch (err) {
         throw withServerReason(err, filename);
     }
+    requireReadyAsset(result);
     return {
+        status: 'ready',
         id: String(result.id ?? result._id),
         digest: storedDigest(result),
         filename,
@@ -144,6 +157,12 @@ async function uploadTaskAssetFile(opts) {
         ...(result.resourceReceipt ? { resourceReceipt: result.resourceReceipt } : {}),
     };
 }
+function requireReadyAsset(asset) {
+    const id = asset?.id ?? asset?._id;
+    if (typeof id !== 'string' || !id.trim() || asset.status !== 'ready') {
+        throw new Error('The server did not confirm a ready Task attachment; the upload is not complete.');
+    }
+}
 /**
  * Put the server's own reason on a refused upload.
  *
@@ -163,6 +182,9 @@ function withServerReason(err, filename) {
     if (!message)
         return err;
     err.message = `${filename}: ${message}${code ? ` (${code})` : ''}`;
+    const recovery = taskAssetUploadRecovery(err);
+    if (recovery)
+        err.message += ` ${resumeHint(recovery.attachmentId)}`;
     return err;
 }
 /**
@@ -236,6 +258,7 @@ async function genericDirectUpload(p) {
         mimeType: p.mimeType,
         sizeBytes: p.size,
         sha256: await sha256OfFile(p.filePath),
+        transport: 'auto',
         role: p.role,
         ...(p.ledger?.identity
             ? {
@@ -246,20 +269,7 @@ async function genericDirectUpload(p) {
             }
             : {}),
     });
-    if (!intent.uploadUrl)
-        return intent.attachment;
-    await postFileToStorage({
-        uploadUrl: intent.uploadUrl,
-        uploadFields: intent.uploadFields ?? {},
-        filePath: p.filePath,
-        size: p.size,
-        filename: p.filename,
-        mimeType: p.mimeType,
-    });
-    return data_provider_1.dataService.completeTaskAttachmentUpload({
-        taskId: p.taskId,
-        attachmentId: intent.attachment.id,
-    });
+    return uploadDirectIntent(p, intent, directUploadProtocol(p.taskId, directAttachmentId(intent)));
 }
 async function sessionDirectUpload(p, target) {
     const intent = await (0, api_fetch_1.apiFetch)(`${target.path}/intent`, {
@@ -270,6 +280,7 @@ async function sessionDirectUpload(p, target) {
             mimeType: p.mimeType,
             sizeBytes: p.size,
             sha256: await sha256OfFile(p.filePath),
+            transport: 'auto',
             ...(p.role ? { role: p.role } : {}),
             ...(p.ledger?.identity
                 ? {
@@ -281,20 +292,237 @@ async function sessionDirectUpload(p, target) {
                 : {}),
         },
     });
-    if (!intent.uploadUrl)
+    return uploadDirectIntent(p, intent, directUploadProtocol(target.taskId, directAttachmentId(intent), target));
+}
+function directUploadProtocol(taskId, attachmentId, target) {
+    const recovery = { taskId, attachmentId, transport: 'multipart' };
+    const identity = { taskId, attachmentId };
+    if (!target)
+        return {
+            recovery,
+            status: () => data_provider_1.dataService.getTaskAssetUploadStatus(identity),
+            sign: (partNumbers) => data_provider_1.dataService.signTaskAssetUploadParts({ ...identity, partNumbers }),
+            record: (part) => data_provider_1.dataService.recordTaskAssetUploadedPart({ ...identity, ...part }),
+            complete: () => data_provider_1.dataService.completeTaskAttachmentUpload(identity),
+        };
+    const uploadPath = `${target.path}/${encodeURIComponent(attachmentId)}`;
+    return {
+        recovery,
+        status: () => (0, api_fetch_1.apiFetch)(`${uploadPath}/upload-status`, {
+            credential: target.credential,
+        }),
+        sign: (partNumbers) => (0, api_fetch_1.apiFetch)(`${uploadPath}/upload-parts/sign`, {
+            method: 'POST', credential: target.credential, body: { partNumbers },
+        }),
+        record: (part) => (0, api_fetch_1.apiFetch)(`${uploadPath}/upload-parts/complete`, {
+            method: 'POST', credential: target.credential, body: part,
+        }),
+        complete: () => (0, api_fetch_1.apiFetch)(`${target.path}/complete`, {
+            method: 'POST', credential: target.credential, body: { attachmentId },
+        }),
+    };
+}
+/** A bounded recovery receipt, never a storage credential or claim that bytes are ready. */
+function taskAssetUploadRecovery(error) {
+    if (!error || typeof error !== 'object')
+        return undefined;
+    const value = error.uploadRecovery;
+    if (!value || typeof value.taskId !== 'string' || typeof value.attachmentId !== 'string' ||
+        value.transport !== 'multipart')
+        return undefined;
+    return { taskId: value.taskId, attachmentId: value.attachmentId, transport: 'multipart',
+        ...(typeof value.sessionId === 'string' ? { sessionId: value.sessionId } : {}) };
+}
+function resumeHint(attachmentId) {
+    return `Upload attachment ${attachmentId} is not confirmed complete. ` +
+        `Use --resume-attachment ${attachmentId} with tasks attachments upload and the same file to recover this exact upload.`;
+}
+async function resumeDirectUpload(file, target) {
+    const taskId = target?.taskId ?? file.taskId;
+    const protocol = directUploadProtocol(taskId, file.attachmentId, target);
+    const progress = await protocol.status();
+    const rawDeclaration = progress?.declaredAttachment;
+    const declaration = rawDeclaration && typeof rawDeclaration === 'object' && !Array.isArray(rawDeclaration)
+        ? rawDeclaration : undefined;
+    const sha256 = await sha256OfFile(file.filePath);
+    if (!declaration || file.size < 1 || declaration.basis !== 'declared_upload_intent' ||
+        declaration.attachmentId !== file.attachmentId || declaration.taskId !== taskId ||
+        declaration.filename !== file.filename || declaration.mimeType !== file.mimeType ||
+        declaration.sizeBytes !== file.size || declaration.sha256 !== sha256 ||
+        typeof declaration.role !== 'string' || !['input', 'evidence', 'deliverable'].includes(declaration.role) ||
+        (file.role !== undefined && declaration.role !== file.role)) {
+        throw new Error('This file does not match the existing upload declaration, or the server cannot verify it. No replacement upload was created.');
+    }
+    if (progress.transport !== 'multipart' || typeof progress.expiresAt !== 'string' ||
+        !Number.isFinite(Date.parse(progress.expiresAt)) ||
+        Date.parse(progress.expiresAt) <= Date.now()) {
+        throw new Error('Only an unexpired multipart upload can be resumed. No replacement upload was created.');
+    }
+    const intent = {
+        attachment: { id: file.attachmentId, status: 'pending' }, uploadUrl: null, uploadFields: null,
+        uploadTransport: 'multipart', partSize: progress.partSize, partCount: progress.expectedParts,
+    };
+    // Even a ready session goes through canonical completion to recover its
+    // verified attachment and original ledger receipt, never its declaration.
+    return uploadDirectIntent(file, intent, protocol);
+}
+function directAttachmentId(intent) {
+    const id = intent?.attachment?.id;
+    if (typeof id !== 'string' || !id.trim()) {
+        throw new Error('The upload intent did not identify a Task attachment.');
+    }
+    return id;
+}
+/** Shared transport mechanics; each caller retains its own authenticated API door. */
+async function uploadDirectIntent(file, intent, protocol) {
+    directAttachmentId(intent);
+    if (intent.attachment.status === 'ready')
         return intent.attachment;
-    await postFileToStorage({
-        uploadUrl: intent.uploadUrl,
-        uploadFields: intent.uploadFields ?? {},
-        filePath: p.filePath,
-        size: p.size,
-        filename: p.filename,
-        mimeType: p.mimeType,
-    });
-    return (0, api_fetch_1.apiFetch)(`${target.path}/complete`, {
-        method: 'POST',
-        credential: target.credential,
-        body: { attachmentId: intent.attachment.id },
+    if ((intent.attachment.status !== undefined && intent.attachment.status !== 'pending') ||
+        (intent.uploadTransport !== undefined && !['single', 'multipart'].includes(intent.uploadTransport))) {
+        throw new Error('The server returned an unusable Task attachment upload intent.');
+    }
+    try {
+        if (intent.uploadTransport === 'multipart') {
+            await uploadMultipartFile(file, intent, protocol);
+        }
+        else {
+            if (!intent.uploadUrl || !intent.uploadFields) {
+                throw new Error('The pending Task attachment has no usable storage grant; it was not uploaded.');
+            }
+            await postFileToStorage({ ...file, uploadUrl: intent.uploadUrl, uploadFields: intent.uploadFields });
+        }
+        const completed = await protocol.complete();
+        requireReadyAsset(completed);
+        if ((completed.id ?? completed._id) !== intent.attachment.id) {
+            throw new Error('Upload completion returned a different Task attachment.');
+        }
+        return completed;
+    }
+    catch (error) {
+        if (intent.uploadTransport !== 'multipart' || !(error instanceof Error))
+            throw error;
+        Object.assign(error, { uploadRecovery: { ...protocol.recovery } });
+        error.message += ` ${resumeHint(intent.attachment.id)}`;
+        throw error;
+    }
+}
+/** Resume only the parts this exact upload still owes. Completion remains server-verified. */
+async function uploadMultipartFile(file, intent, protocol) {
+    const partSize = intent.partSize;
+    if (!Number.isSafeInteger(partSize) || !partSize || partSize < 1) {
+        throw new Error('The multipart grant has no valid part size.');
+    }
+    const partCount = Math.ceil(file.size / partSize);
+    if (partCount > 10000 || (intent.partCount !== undefined && intent.partCount !== partCount)) {
+        throw new Error('The multipart grant does not match the file size.');
+    }
+    const lengthOf = (partNumber) => Math.min(partSize, file.size - (partNumber - 1) * partSize);
+    let sessionId;
+    const inspect = (progress) => {
+        if (!progress || typeof progress.sessionId !== 'string' || !progress.sessionId ||
+            (sessionId && progress.sessionId !== sessionId) || progress.transport !== 'multipart' ||
+            progress.partSize !== partSize || progress.expectedSize !== file.size ||
+            progress.expectedParts !== partCount || !Array.isArray(progress.receivedParts) ||
+            !['created', 'receiving', 'landed', 'verified', 'scanning', 'canonicalizing', 'ready'].includes(progress.state)) {
+            throw new Error('The server returned inconsistent multipart upload progress.');
+        }
+        sessionId = progress.sessionId;
+        const received = new Set();
+        let bytes = 0;
+        for (const part of progress.receivedParts) {
+            if (!Number.isInteger(part.partNumber) || part.partNumber < 1 || part.partNumber > partCount ||
+                received.has(part.partNumber) || part.byteLength !== lengthOf(part.partNumber)) {
+                throw new Error('The server returned an invalid multipart part receipt.');
+            }
+            received.add(part.partNumber);
+            bytes += part.byteLength;
+        }
+        if (progress.uploadedBytes !== bytes) {
+            throw new Error('The server returned an inconsistent multipart byte count.');
+        }
+        return received;
+    };
+    let progress = await protocol.status();
+    const received = inspect(progress);
+    protocol.recovery.sessionId = progress.sessionId;
+    for (let partNumber = 1; partNumber <= partCount; partNumber += 1) {
+        if (received.has(partNumber))
+            continue;
+        if (!['created', 'receiving'].includes(progress.state)) {
+            throw new Error('The multipart upload cannot receive its missing parts.');
+        }
+        const signed = await protocol.sign([partNumber]);
+        inspect(signed?.progress);
+        if (signed.sessionId !== sessionId || !Array.isArray(signed.parts) || signed.parts.length !== 1 ||
+            signed.parts[0].partNumber !== partNumber || typeof signed.parts[0].url !== 'string') {
+            throw new Error('The server did not grant the requested multipart part.');
+        }
+        const receipt = await putFilePartToStorage({
+            uploadUrl: signed.parts[0].url, filePath: file.filePath,
+            offset: (partNumber - 1) * partSize, byteLength: lengthOf(partNumber),
+        });
+        const recorded = await protocol.record({ partNumber, ...receipt });
+        const landed = inspect(recorded?.progress);
+        if (recorded.sessionId !== sessionId || recorded.recorded !== true || !landed.has(partNumber)) {
+            throw new Error('The server did not acknowledge the uploaded multipart part.');
+        }
+        progress = recorded.progress;
+    }
+    const final = await protocol.status();
+    if (inspect(final).size !== partCount || final.uploadedBytes !== file.size ||
+        fs.statSync(file.filePath).size !== file.size) {
+        throw new Error('The multipart upload is incomplete or the file changed during upload.');
+    }
+}
+/** PUT one bounded file range and report only the actual storage receipt and streamed bytes. */
+async function putFilePartToStorage(p) {
+    const url = new URL(p.uploadUrl);
+    if (!['http:', 'https:'].includes(url.protocol))
+        throw new Error('Unsupported storage upload protocol.');
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let sent = 0;
+        let ended = false;
+        let etag;
+        const stream = fs.createReadStream(p.filePath, { start: p.offset, end: p.offset + p.byteLength - 1 });
+        const fail = (message) => {
+            if (settled)
+                return;
+            settled = true;
+            stream.destroy();
+            req.destroy();
+            reject(new Error(message));
+        };
+        const done = () => {
+            if (settled || !ended || !etag)
+                return;
+            if (sent !== p.byteLength)
+                return fail('The file changed while its multipart part was uploaded.');
+            settled = true;
+            resolve({ etag, byteLength: sent });
+        };
+        const req = (url.protocol === 'http:' ? http : https).request(url, {
+            method: 'PUT', headers: { 'Content-Length': String(p.byteLength) },
+        }, (res) => {
+            const status = res.statusCode ?? 0;
+            const actualEtag = res.headers.etag;
+            if (status < 200 || status >= 300)
+                return fail(`Storage rejected the multipart part (${status}).`);
+            if (typeof actualEtag !== 'string' || !actualEtag.trim() || actualEtag.length > 220) {
+                return fail('Storage did not return a valid multipart part receipt.');
+            }
+            res.on('error', () => fail('Storage multipart response failed.'));
+            res.on('aborted', () => fail('Storage multipart response was interrupted.'));
+            res.on('end', () => { etag = actualEtag; done(); });
+            res.resume();
+        });
+        req.on('error', () => fail('Storage multipart upload failed.'));
+        req.setTimeout(60000, () => fail('Storage multipart upload timed out.'));
+        stream.on('data', (chunk) => { sent += chunk.length; });
+        stream.on('error', () => fail('The multipart file could not be read.'));
+        stream.on('end', () => { ended = true; done(); });
+        stream.pipe(req);
     });
 }
 /** sha256 of a file, read as a stream: a 250MB recording never sits in memory. */

package/dist/lib/task-batch.d.ts

@@ -8,7 +8,7 @@
  * sends a command back to its serial path. The shared transport owns each
  * request's fresh idempotency key.
  */
-import { type TaskBatchItemResult, type TaskBatchPatchItem } from '@skrr-ai/data-provider';
+import { type TaskBatchItemResult, type TaskBatchPatchItem, type SpaceWriteProposalRef } from '@skrr-ai/data-provider';
 export type ApiFailure = {
     message: string;
     status?: number;
@@ -45,6 +45,18 @@ export type BatchCreatedRow = {
     status: 'created' | 'exists';
     externalKey?: string;
 };
+/**
+ * A node the Space write policy held for approval (OSK-17988): nothing was
+ * written, and a person approves it from the named bundle. A node that needs a
+ * held one as its parent or blocker is held with it (`depends_on_held`): it
+ * cannot be placed until the held one exists, and is not a failure.
+ */
+export type BatchHeldRow = {
+    key: string;
+    reason: 'pending_approval' | 'depends_on_held';
+    proposal?: SpaceWriteProposalRef;
+    externalKey?: string;
+};
 export type BatchCreateFailure = {
     key: string;
     /** Not attempted because its parent was not created (or an earlier chunk failed). */
@@ -65,6 +77,8 @@ export type BatchCreateOutcome = {
     supported: true;
     rows: BatchCreatedRow[];
     failures: BatchCreateFailure[];
+    /** Held for approval by the Space write policy, and the nodes waiting on them. */
+    held: BatchHeldRow[];
     /** Requests made to the batch route, retries included. */
     rounds: number;
 };

package/dist/lib/task-batch.js

@@ -183,6 +183,8 @@ async function createNodesViaBatch(nodes, mapping, options = {}) {
     const position = new Map(nodes.map((node, index) => [node.key, index]));
     const rows = [];
     const failures = [];
+    const held = [];
+    const heldKeys = new Set();
     const chunkSize = data_provider_1.TASK_BATCH_MAX_ITEMS ?? 100;
     let remaining = nodes.filter((node) => !(node.key in mapping));
     /** Nodes whose last submission ended without a verdict: they may exist. */
@@ -230,6 +232,7 @@ async function createNodesViaBatch(nodes, mapping, options = {}) {
         const items = [];
         const sent = [];
         const dropped = new Set();
+        const heldDropped = new Set();
         for (const [i, node] of chunk.entries()) {
             const { parentId: _ignored, ...payload } = node.payload;
             const item = { ...payload, tempId: `n${i}` };
@@ -270,6 +273,14 @@ async function createNodesViaBatch(nodes, mapping, options = {}) {
                     }
                 }
             }
+            const waitsOnHeld = (node.parentKey && heldKeys.has(node.parentKey)) ||
+                (node.blockerKeys ?? []).some((key) => heldKeys.has(key));
+            if (unresolved && waitsOnHeld) {
+                heldDropped.add(node.key);
+                heldKeys.add(node.key);
+                held.push({ key: node.key, reason: 'depends_on_held' });
+                continue;
+            }
             if (unresolved) {
                 dropped.add(node.key);
                 failures.push({
@@ -291,8 +302,11 @@ async function createNodesViaBatch(nodes, mapping, options = {}) {
         }
         // A dropped node is a failure already recorded; it leaves the queue now, or
         // it would be examined, and recorded, again every round.
-        remaining = remaining.filter((node) => !dropped.has(node.key));
+        remaining = remaining.filter((node) => !dropped.has(node.key) && !heldDropped.has(node.key));
         const upstreamBroken = dropped.size > 0;
+        // Every node of this chunk waits on a held one; the queue already moved on.
+        if (items.length === 0 && !upstreamBroken)
+            continue;
         if (items.length === 0) {
             // Everything in this chunk depended on something that is gone, so nothing
             // further can be built on it.
@@ -354,6 +368,24 @@ async function createNodesViaBatch(nodes, mapping, options = {}) {
                 const result = results.get(i);
                 const code = result?.error?.code;
                 const status = result?.error?.status ?? 0;
+                // Held for approval: nothing was written, and resubmitting would only
+                // find the same approval item. Not a failure, and not retried.
+                if (result?.status === 'pending_approval') {
+                    held.push({
+                        key: node.key,
+                        reason: 'pending_approval',
+                        ...(result.proposal ? { proposal: result.proposal } : {}),
+                        ...(result.externalKey ? { externalKey: result.externalKey } : {}),
+                    });
+                    heldKeys.add(node.key);
+                    continue;
+                }
+                if (result?.status === 'skipped' &&
+                    (code === 'BATCH_PARENT_PENDING_APPROVAL' || code === 'BATCH_BLOCKER_PENDING_APPROVAL')) {
+                    held.push({ key: node.key, reason: 'depends_on_held' });
+                    heldKeys.add(node.key);
+                    continue;
+                }
                 const confirmed = result?.ok && result.id;
                 if (confirmed) {
                     mapping[node.key] = result.id;
@@ -467,7 +499,8 @@ async function createNodesViaBatch(nodes, mapping, options = {}) {
     }
     rows.sort((a, b) => (position.get(a.key) ?? 0) - (position.get(b.key) ?? 0));
     failures.sort((a, b) => (position.get(a.key) ?? 0) - (position.get(b.key) ?? 0));
-    return { supported: true, rows, failures, rounds: round };
+    held.sort((a, b) => (position.get(a.key) ?? 0) - (position.get(b.key) ?? 0));
+    return { supported: true, rows, failures, held, rounds: round };
 }
 /**
  * Apply `updates` in chunks; `results[i]` answers `updates[i]`. A chunk the

package/dist/lib/task-operation-watch.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Read-only waiting for a server-authoritative Task Operation.
+ *
+ * A Task status is intentionally not used as a completion signal here. One
+ * Task can have several sequential or competing operations, so only the
+ * operation's immutable id and server projection may settle this wait.
+ */
+export type TaskOperationProjection = {
+    object?: string;
+    schemaVersion?: number;
+    operationId?: string;
+    taskId?: string;
+    intent?: string;
+    state?: string;
+    phase?: string;
+    terminal?: boolean;
+    outcome?: string;
+    updatedAt?: string;
+    recovery?: unknown;
+    [key: string]: unknown;
+};
+export type TaskOperationCheckpoint = {
+    object: 'task_operation_watch_checkpoint';
+    schemaVersion: 1;
+    observedAt: string;
+    taskId: string;
+    operationId: string;
+    observation: 'observed' | 'timeout';
+    changed: boolean;
+    terminal: boolean;
+    result: 'pending' | 'succeeded' | 'failed' | 'unknown';
+    operation: TaskOperationProjection | null;
+};
+export type TaskOperationWatchOptions = {
+    taskId: string;
+    operationId: string;
+    intervalMs: number;
+    timeoutMs: number | null;
+    read: (taskId: string, operationId: string) => Promise<TaskOperationProjection>;
+    onCheckpoint: (checkpoint: TaskOperationCheckpoint) => void | Promise<void>;
+    sleep?: (milliseconds: number) => Promise<void>;
+    now?: () => number;
+};
+export type TaskOperationWatchResult = {
+    terminal: boolean;
+    result: 'succeeded' | 'failed';
+    operation: TaskOperationProjection;
+};
+/** Parse the same bounded duration grammar used by `tasks watch`. */
+export declare function parseTaskOperationWatchDuration(value: string | undefined): number | null;
+/**
+ * Classify only server-declared terminal status or the narrow, stable terminal
+ * vocabulary. An absent/malformed/unknown projection never becomes success by
+ * inference, and neither does a Task's own workflow status.
+ */
+export declare function classifyTaskOperation(operation: TaskOperationProjection | null): {
+    terminal: boolean;
+    result: 'pending' | 'succeeded' | 'failed' | 'unknown';
+};
+/**
+ * Poll one immutable operation until it reaches an authoritative terminal
+ * result. Every read is emitted as a checkpoint so JSON consumers can prove
+ * liveness even where a server does not yet offer an event stream.
+ */
+export declare function watchTaskOperation(options: TaskOperationWatchOptions): Promise<TaskOperationWatchResult>;
+export declare function taskOperationCheckpointLine(checkpoint: TaskOperationCheckpoint): string;