@skrr-ai/cli 0.1.107 → 0.1.109

package/dist/lib/task-batch.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.batchRetryPolicy = void 0;
 exports.describeApiFailure = describeApiFailure;
 exports.isBatchRouteMissing = isBatchRouteMissing;
 exports.chunkItems = chunkItems;
@@ -81,31 +82,51 @@ async function reconcileSubmittedNodes(nodes, mapping, error, deadlineAt = Date.
                 let timer;
                 try {
                     const read = (0, tasks_1.findTaskByExternalKey)({
-                        externalKey, spaceId: node.payload.spaceId, goalId: node.payload.goalId,
+                        externalKey,
+                        spaceId: node.payload.spaceId,
+                        goalId: node.payload.goalId,
                     });
-                    const existing = await Promise.race([read, new Promise((resolve) => {
+                    const existing = await Promise.race([
+                        read,
+                        new Promise((resolve) => {
                             timer = setTimeout(() => resolve(null), Math.max(1, deadlineAt - Date.now()));
-                        })]);
+                        }),
+                    ]);
                     if (existing?.task?.externalKey === externalKey && (0, tasks_1.taskId)(existing.task)) {
                         const id = (0, tasks_1.taskId)(existing.task);
                         mapping[node.key] = id;
-                        rows.push({ key: node.key, id, status: 'exists', externalKey,
-                            ...(typeof existing.task.identifier === 'string' ? { identifier: existing.task.identifier } : {}),
+                        rows.push({
+                            key: node.key,
+                            id,
+                            status: 'exists',
+                            externalKey,
+                            ...(typeof existing.task.identifier === 'string'
+                                ? { identifier: existing.task.identifier }
+                                : {}),
                         });
                         return;
                     }
                 }
-                catch { /* A failed read does not prove the write failed. */ }
+                catch {
+                    /* A failed read does not prove the write failed. */
+                }
                 finally {
                     clearTimeout(timer);
                 }
             }
-            failures.push({ key: node.key, skipped: false, outcome: 'unknown',
+            failures.push({
+                key: node.key,
+                skipped: false,
+                outcome: 'unknown',
                 ...(externalKey ? { externalKey } : {}),
-                error: { ...error, code: 'BATCH_OUTCOME_UNKNOWN', retryable: Boolean(externalKey),
+                error: {
+                    ...error,
+                    code: 'BATCH_OUTCOME_UNKNOWN',
+                    retryable: Boolean(externalKey),
                     message: `The result for "${node.key}" is unknown. ` +
-                        (externalKey ? `No committed task was confirmed by external key "${externalKey}"; the original write may still finish. Re-run the same keyed tree to reconcile and resume.` :
-                            'This node has no stable external key. Inspect the Space before another write; do not re-run --fresh blindly.'),
+                        (externalKey
+                            ? `No committed task was confirmed by external key "${externalKey}"; the original write may still finish. Re-run the same keyed tree to reconcile and resume.`
+                            : 'This node has no stable external key. Inspect the Space before another write; do not re-run --fresh blindly.'),
                 },
             });
         }));
@@ -116,47 +137,181 @@ async function reconcileSubmittedNodes(nodes, mapping, error, deadlineAt = Date.
     return { rows, failures };
 }
 /**
- * Create `nodes` (parents before children) in chunks. `mapping` holds key -> id
- * for nodes that already exist and is extended in place. Stops after the first
- * chunk that reports a failure, as the serial path stopped at its first failure.
+ * How a create that is not finishing is retried. A seam rather than constants so
+ * a test can run the whole policy without waiting through it.
+ *
+ * Each round that confirms nothing waits the next interval and counts toward the
+ * limit; a round that confirms anything resets it. The total wait is bounded
+ * (about 15 s), on purpose: this is a courtesy to a server that is briefly slow
+ * or rate-limited, not a promise to outlast an outage — past it the command says
+ * what is unknown and how to continue.
+ */
+exports.batchRetryPolicy = {
+    backoffMs: [1000, 2000, 4000, 8000],
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+};
+const SERVER_DEADLINE_CODES = new Set(['BATCH_DEADLINE_EXCEEDED']);
+/** A row the server skipped because something it depends on never came to exist. */
+const UPSTREAM_FAILED_CODES = new Set(['BATCH_PARENT_NOT_CREATED', 'BATCH_BLOCKER_NOT_CREATED']);
+function isUncertainTransport(error) {
+    return (!error.status ||
+        error.status === 408 ||
+        error.status === 425 ||
+        error.status === 429 ||
+        error.status >= 500 ||
+        error.code === 'IDEMPOTENCY_IN_PROGRESS');
+}
+function stableKeyOf(node) {
+    const key = node.payload.externalKey;
+    return typeof key === 'string' && key.trim() ? key : undefined;
+}
+/**
+ * Create `nodes` — parents and blockers BEFORE what depends on them — until every
+ * one exists, or say precisely which do not and why.
+ *
+ * One request is a bounded unit of work, not the whole job: the server answers
+ * within a response budget, creating what it can and reporting the rest as not
+ * started (`BATCH_DEADLINE_EXCEEDED`) or still in flight (`pending`). That is a
+ * normal, successful answer, so this loop is what turns it into a finished tree:
+ * submit, record what is confirmed, submit what is left. It used to stop at the
+ * first row the server had not confirmed and hand the person a `--resume` to
+ * type — once per row or two, against a server that confirms a row or two per
+ * request (OSK-S-440 #1, #3, #4).
+ *
+ * The one rule that makes resubmitting safe is the one the server enforces: a
+ * node with a stable `externalKey` can be created once. A submitted write whose
+ * outcome is unknown is therefore READ first (`reconcileSubmittedNodes`), and only
+ * if the key is still absent is the node sent again — where, if the first write
+ * has landed in the meantime, the unique index turns it into `exists`. A node with
+ * no stable key is never resubmitted after an uncertain outcome, because nothing
+ * could tell the second write from a duplicate; that case stops and says so, as
+ * before.
+ *
+ * `mapping` holds key -> id for nodes that already exist and is extended in place.
  */
-async function createNodesViaBatch(nodes, mapping) {
+async function createNodesViaBatch(nodes, mapping, options = {}) {
+    const startedAt = Date.now();
+    const position = new Map(nodes.map((node, index) => [node.key, index]));
     const rows = [];
     const failures = [];
-    for (const [chunkIndex, chunk] of chunkItems(nodes).entries()) {
+    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. */
+    const unknown = new Set();
+    let stalled = 0;
+    let round = 0;
+    let lastError;
+    const report = (waiting) => options.onProgress?.({
+        confirmed: rows.length,
+        total: nodes.length,
+        round,
+        elapsedMs: Date.now() - startedAt,
+        ...(waiting ? { waiting } : {}),
+    });
+    /** Everything still owed becomes a failure that says whether it may exist. */
+    const giveUp = (reason) => {
+        for (const node of remaining) {
+            const externalKey = stableKeyOf(node);
+            const maybeThere = unknown.has(node.key);
+            failures.push({
+                key: node.key,
+                skipped: !maybeThere,
+                outcome: maybeThere ? 'unknown' : 'not_attempted',
+                ...(externalKey ? { externalKey } : {}),
+                error: {
+                    ...(maybeThere && lastError ? lastError : {}),
+                    message: maybeThere
+                        ? `The result for "${node.key}" is unknown: ${reason}` +
+                            (externalKey
+                                ? ' Re-run the same keyed tree with --resume to confirm it and continue.'
+                                : ' This node has no stable external key. Inspect the Space before another write; do not re-run --fresh blindly.')
+                        : `"${node.key}" was not started: ${reason}`,
+                    code: maybeThere ? 'BATCH_OUTCOME_UNKNOWN' : 'BATCH_NOT_ATTEMPTED',
+                    retryable: maybeThere ? Boolean(externalKey) : true,
+                },
+            });
+        }
+        remaining = [];
+    };
+    while (remaining.length > 0) {
+        round += 1;
+        const chunk = remaining.slice(0, chunkSize);
         const inChunk = new Map(chunk.map((node, i) => [node.key, `n${i}`]));
         const items = [];
         const sent = [];
+        const dropped = new Set();
         for (const [i, node] of chunk.entries()) {
             const { parentId: _ignored, ...payload } = node.payload;
             const item = { ...payload, tempId: `n${i}` };
+            let unresolved;
             if (node.parentKey) {
                 const sameChunk = inChunk.get(node.parentKey);
                 if (sameChunk)
                     item.parentTempId = sameChunk;
                 else if (mapping[node.parentKey])
                     item.parentId = mapping[node.parentKey];
-                else {
-                    failures.push({
-                        key: node.key,
-                        skipped: true,
-                        error: {
-                            message: `Parent "${node.parentKey}" was not created, so "${node.key}" was not attempted`,
-                            code: 'BATCH_PARENT_NOT_CREATED',
-                            retryable: false,
-                        },
-                    });
-                    continue;
-                }
+                else
+                    unresolved = `Parent "${node.parentKey}"`;
             }
             else if (node.payload.parentId) {
                 item.parentId = node.payload.parentId;
             }
+            if (!unresolved && node.blockerKeys?.length) {
+                const tempIds = [];
+                const ids = [];
+                for (const blockerKey of node.blockerKeys) {
+                    const sameChunk = inChunk.get(blockerKey);
+                    if (sameChunk)
+                        tempIds.push(sameChunk);
+                    else if (mapping[blockerKey])
+                        ids.push(mapping[blockerKey]);
+                    else {
+                        unresolved = `Blocker "${blockerKey}"`;
+                        break;
+                    }
+                }
+                if (!unresolved) {
+                    if (tempIds.length)
+                        item.blockedByTempIds = tempIds;
+                    if (ids.length) {
+                        item.blockedByIds = [
+                            ...new Set([...(payload.blockedByIds ?? []), ...ids]),
+                        ];
+                    }
+                }
+            }
+            if (unresolved) {
+                dropped.add(node.key);
+                failures.push({
+                    key: node.key,
+                    skipped: true,
+                    outcome: 'not_attempted',
+                    error: {
+                        message: `${unresolved} was not created, so "${node.key}" was not attempted`,
+                        code: node.blockerKeys?.length
+                            ? 'BATCH_BLOCKER_NOT_CREATED'
+                            : 'BATCH_PARENT_NOT_CREATED',
+                        retryable: false,
+                    },
+                });
+                continue;
+            }
             items.push(item);
             sent.push(node);
         }
-        if (items.length === 0)
+        // 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));
+        const upstreamBroken = dropped.size > 0;
+        if (items.length === 0) {
+            // Everything in this chunk depended on something that is gone, so nothing
+            // further can be built on it.
+            giveUp('a node it depends on was not created.');
             break;
+        }
+        let confirmedThisRound = 0;
+        let hardFailure = false;
+        let waitReason = 'the server confirmed nothing';
         let response;
         try {
             response = await data_provider_1.dataService.createTasksBatch(items, {
@@ -164,63 +319,124 @@ async function createNodesViaBatch(nodes, mapping) {
             });
         }
         catch (err) {
-            if (chunkIndex === 0 && isBatchRouteMissing(err))
+            if (round === 1 && isBatchRouteMissing(err))
                 return { supported: false };
             const error = describeApiFailure(err);
-            const uncertain = !error.status || error.status === 408 || error.status >= 500 || error.code === 'IDEMPOTENCY_IN_PROGRESS';
-            if (uncertain) {
+            lastError = error;
+            if (isUncertainTransport(error)) {
+                // Read before writing again: a lost response is not a lost write.
                 const recovered = await reconcileSubmittedNodes(sent, mapping, error);
-                rows.push(...recovered.rows);
-                failures.push(...recovered.failures);
-                // Even a fully reconciled chunk stops here: no extra write follows a
-                // lost response during this run. Later chunks are explicitly unstarted.
-                const remaining = nodes.slice((chunkIndex + 1) * (data_provider_1.TASK_BATCH_MAX_ITEMS ?? 100));
-                for (const node of remaining)
-                    failures.push({ key: node.key, skipped: true,
-                        outcome: 'not_attempted', externalKey: node.payload.externalKey,
-                        error: { message: 'Not started after a batch transport failure; resume the same keyed tree.', code: 'BATCH_NOT_ATTEMPTED', retryable: true }, });
+                for (const row of recovered.rows) {
+                    rows.push(row);
+                    unknown.delete(row.key);
+                    confirmedThisRound += 1;
+                }
+                const stillUnknown = recovered.failures.map((f) => f.key);
+                for (const key of stillUnknown)
+                    unknown.add(key);
+                const unkeyed = sent.filter((n) => stillUnknown.includes(n.key) && !stableKeyOf(n));
+                remaining = remaining.filter((node) => !(node.key in mapping));
+                if (unkeyed.length > 0) {
+                    // No stable key: a second write could not be told from a duplicate.
+                    // Say what is unknown and stop, exactly as before.
+                    for (const f of recovered.failures)
+                        failures.push(f);
+                    remaining = remaining.filter((node) => !recovered.failures.some((f) => f.key === node.key));
+                    giveUp('the request was lost before the server answered.');
+                    break;
+                }
+                waitReason = `the request did not complete (${error.status ?? 'no response'})`;
             }
             else {
-                for (const node of sent)
+                // The whole request was refused (400/401/403/413/422...): a decision, not a glitch.
+                for (const node of sent) {
                     failures.push({ key: node.key, skipped: false, outcome: 'failed', error });
-                for (const node of nodes.slice((chunkIndex + 1) * (data_provider_1.TASK_BATCH_MAX_ITEMS ?? 100))) {
-                    failures.push({ key: node.key, skipped: true, outcome: 'not_attempted',
-                        error: { message: 'Not started after a batch refusal.', code: 'BATCH_NOT_ATTEMPTED', retryable: true } });
                 }
+                remaining = remaining.filter((node) => !sent.includes(node));
+                giveUp('the batch request was refused.');
+                break;
             }
-            break;
         }
-        let failed = false;
-        const reconciliationDeadlineAt = Date.now() + 5000;
-        for (const [i, node] of sent.entries()) {
-            const result = response.results?.find((r) => r.index === i);
-            if (!result || result.status === 'pending' || (result.ok && !result.id) || (result.error?.status ?? 0) >= 500) {
-                const recovered = await reconcileSubmittedNodes([{ ...node, payload: {
-                            ...node.payload, ...(result?.externalKey ? { externalKey: result.externalKey } : {}),
-                        } }], mapping, {
-                    message: 'Batch did not confirm this submitted write', code: 'BATCH_OUTCOME_UNKNOWN', retryable: true,
-                }, reconciliationDeadlineAt);
-                rows.push(...recovered.rows);
-                failures.push(...recovered.failures);
-                failed = true;
-                continue;
-            }
-            if (result.ok && result.id) {
-                mapping[node.key] = result.id;
-                rows.push({
-                    key: node.key,
-                    id: result.id,
-                    ...(result.identifier ? { identifier: result.identifier } : {}),
-                    status: result.status === 'exists' ? 'exists' : 'created',
-                    ...(result.externalKey ? { externalKey: result.externalKey } : {}),
-                });
-            }
-            else {
-                failed = true;
+        if (response) {
+            const results = new Map((response.results ?? []).map((r) => [r.index, r]));
+            const retryLater = [];
+            const reconcileDeadlineAt = Date.now() + 5000;
+            for (const [i, node] of sent.entries()) {
+                const result = results.get(i);
+                const code = result?.error?.code;
+                const status = result?.error?.status ?? 0;
+                const confirmed = result?.ok && result.id;
+                if (confirmed) {
+                    mapping[node.key] = result.id;
+                    rows.push({
+                        key: node.key,
+                        id: result.id,
+                        ...(result.identifier ? { identifier: result.identifier } : {}),
+                        status: result.status === 'exists' ? 'exists' : 'created',
+                        ...(result.externalKey ? { externalKey: result.externalKey } : {}),
+                    });
+                    unknown.delete(node.key);
+                    confirmedThisRound += 1;
+                    continue;
+                }
+                // Submitted, outcome not established: pending, absent from a 200, an ok
+                // row with no id, or a 5xx the item handler returned. Read, don't guess.
+                if (!result || result.status === 'pending' || result.ok || status >= 500) {
+                    const recovered = await reconcileSubmittedNodes([
+                        {
+                            ...node,
+                            payload: {
+                                ...node.payload,
+                                ...(result?.externalKey ? { externalKey: result.externalKey } : {}),
+                            },
+                        },
+                    ], mapping, {
+                        message: 'Batch did not confirm this submitted write',
+                        code: 'BATCH_OUTCOME_UNKNOWN',
+                        retryable: true,
+                    }, reconcileDeadlineAt);
+                    if (recovered.rows.length > 0) {
+                        for (const row of recovered.rows)
+                            rows.push(row);
+                        unknown.delete(node.key);
+                        confirmedThisRound += 1;
+                    }
+                    else if (stableKeyOf(node) || result?.externalKey) {
+                        unknown.add(node.key);
+                        retryLater.push(node);
+                        lastError = recovered.failures[0]?.error ?? lastError;
+                    }
+                    else {
+                        failures.push(...recovered.failures);
+                        hardFailure = true;
+                    }
+                    continue;
+                }
+                // Never started: the response budget ran out, or the rate window did.
+                if (result.status === 'skipped' &&
+                    (SERVER_DEADLINE_CODES.has(code ?? '') ||
+                        code === 'BATCH_RATE_LIMITED' ||
+                        status === 429 ||
+                        status === 408)) {
+                    retryLater.push(node);
+                    if (code === 'BATCH_RATE_LIMITED' || status === 429)
+                        waitReason = 'the create rate limit is spent for this minute';
+                    continue;
+                }
+                // Something it depends on failed, or the row itself was refused for good.
+                const retryable = Boolean(result.error?.retryable) && result.status !== 'skipped';
+                if (retryable) {
+                    retryLater.push(node);
+                    lastError = describeApiFailure(result.error);
+                    continue;
+                }
+                hardFailure = true;
                 failures.push({
                     key: node.key,
                     skipped: result.status === 'skipped',
-                    outcome: result.status === 'skipped' ? 'not_attempted' : 'failed',
+                    outcome: result.status === 'skipped' || UPSTREAM_FAILED_CODES.has(code ?? '')
+                        ? 'not_attempted'
+                        : 'failed',
                     ...(result.externalKey ? { externalKey: result.externalKey } : {}),
                     error: result.error
                         ? {
@@ -232,17 +448,37 @@ async function createNodesViaBatch(nodes, mapping) {
                         : { message: 'Task was not created', retryable: false },
                 });
             }
-        }
-        if (failed) {
-            for (const node of nodes.slice((chunkIndex + 1) * (data_provider_1.TASK_BATCH_MAX_ITEMS ?? 100))) {
-                failures.push({ key: node.key, skipped: true, outcome: 'not_attempted',
-                    externalKey: node.payload.externalKey,
-                    error: { message: 'Not started after an incomplete batch; resume the same keyed tree.', code: 'BATCH_NOT_ATTEMPTED', retryable: true }, });
+            const retrySet = new Set(retryLater.map((n) => n.key));
+            remaining = remaining.filter((node) => !(node.key in mapping) && (retrySet.has(node.key) || !sent.includes(node)));
+            // Rows refused for good leave the queue; the loop stops below.
+            if (hardFailure) {
+                remaining = remaining.filter((node) => !failures.some((f) => f.key === node.key));
             }
+        }
+        report();
+        if (hardFailure || upstreamBroken) {
+            giveUp('an earlier node was refused; nothing that depends on it can be created.');
             break;
         }
+        if (remaining.length === 0)
+            break;
+        if (confirmedThisRound > 0) {
+            stalled = 0;
+        }
+        else {
+            stalled += 1;
+            if (stalled >= exports.batchRetryPolicy.backoffMs.length) {
+                giveUp(`no progress after ${stalled} attempts (${waitReason}${lastError?.code ? `; last: ${lastError.code}` : ''}).`);
+                break;
+            }
+            const ms = exports.batchRetryPolicy.backoffMs[stalled - 1];
+            report({ ms, reason: waitReason });
+            await exports.batchRetryPolicy.sleep(ms);
+        }
     }
-    return { supported: true, rows, failures };
+    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 };
 }
 /**
  * Apply `updates` in chunks; `results[i]` answers `updates[i]`. A chunk the

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

@@ -29,3 +29,8 @@ export declare function describeEstimate(economics: unknown): string;
  * scored and sorts after every row that is.
  */
 export declare function economicsScoreText(economics: unknown): string;
+/**
+ * One line for a `task.economics.*` Activity event (OSK-15365): the revision, the claim after the
+ * change and the claim it replaced, so `tasks activity` shows from-what-to-what without `--json`.
+ */
+export declare function describeEconomicsChange(data: unknown): string;

package/dist/lib/task-economics.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.economicsFromFlags = economicsFromFlags;
 exports.describeEstimate = describeEstimate;
 exports.economicsScoreText = economicsScoreText;
+exports.describeEconomicsChange = describeEconomicsChange;
 const data_provider_1 = require("@skrr-ai/data-provider");
 /**
  * A flag's amount as a number, or an error that names the flag and the value (OSK-15366). A raw
@@ -85,3 +86,17 @@ function economicsScoreText(economics) {
     const score = (0, data_provider_1.proposalEconomicsRank)(economics).score;
     return score === null || !Number.isFinite(score) ? '—' : String(Math.round(score));
 }
+/**
+ * One line for a `task.economics.*` Activity event (OSK-15365): the revision, the claim after the
+ * change and the claim it replaced, so `tasks activity` shows from-what-to-what without `--json`.
+ */
+function describeEconomicsChange(data) {
+    const value = (data && typeof data === 'object' ? data : {});
+    const now = value.change === 'retracted' || !value.after ? 'no estimate' : describeEstimate(value.after);
+    let was = 'no estimate';
+    if (value.before)
+        was = describeEstimate(value.before);
+    else if (value.beforeUnavailable)
+        was = 'not recorded';
+    return `r${value.revision ?? '?'} ${value.change ?? 'changed'}: ${now} (was: ${was})`;
+}

package/dist/lib/task-recurrence-outcome.d.ts

@@ -1,10 +1,10 @@
 /**
- * What completing a recurring occurrence did to its series, as a sentence (OSK-15483).
- *
- * `tasks complete` armed the next occurrence (or deliberately did not) and printed nothing either way, so a
- * person could not tell that the series continued, or that the third of three runs had ended it. The server
- * reports `recurrence` on the completion; this words it.
+ * The ONE way back for a series whose next occurrence was never armed (OSK-15338), named by every
+ * surface that reports the failure. `tasks schedule` refuses the finished occurrence that carries
+ * the failure, so naming it (as `tasks show` did) sent people to a command that could never work.
+ * An `invalid_pattern` failure has no cure without a new pattern, so the hint carries `--cron`.
  */
+export declare function recurrenceRearmHint(code: unknown, taskRef?: string, bin?: string): string;
 export type RecurrenceOutcome = {
     state?: string;
     reason?: string;
@@ -16,4 +16,4 @@ export type RecurrenceOutcome = {
     armFailure?: unknown;
 };
 /** One line, or null when the Task does not recur (or an older server did not say). */
-export declare function recurrenceOutcomeLine(outcome: RecurrenceOutcome | null | undefined): string | null;
+export declare function recurrenceOutcomeLine(outcome: RecurrenceOutcome | null | undefined, taskRef?: string, bin?: string): string | null;

package/dist/lib/task-recurrence-outcome.js

@@ -1,13 +1,32 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.recurrenceRearmHint = recurrenceRearmHint;
 exports.recurrenceOutcomeLine = recurrenceOutcomeLine;
+/**
+ * What completing a recurring occurrence did to its series, as a sentence (OSK-15483).
+ *
+ * `tasks complete` armed the next occurrence (or deliberately did not) and printed nothing either way, so a
+ * person could not tell that the series continued, or that the third of three runs had ended it. The server
+ * reports `recurrence` on the completion; this words it.
+ */
+const data_provider_1 = require("@skrr-ai/data-provider");
+/**
+ * The ONE way back for a series whose next occurrence was never armed (OSK-15338), named by every
+ * surface that reports the failure. `tasks schedule` refuses the finished occurrence that carries
+ * the failure, so naming it (as `tasks show` did) sent people to a command that could never work.
+ * An `invalid_pattern` failure has no cure without a new pattern, so the hint carries `--cron`.
+ */
+function recurrenceRearmHint(code, taskRef = '<task-id>', bin = 'skrr') {
+    const fix = code === 'invalid_pattern' ? ' --cron "<minute hour day month weekday>"' : '';
+    return `Re-arm the series with \`${bin} tasks rearm-recurrence ${taskRef}${fix}\`.`;
+}
 const ENDED_BECAUSE = {
     max_runs: 'it reached its maximum number of runs',
     end_date: 'its end date has passed',
     no_next_occurrence: 'its pattern has no further occurrence',
 };
 /** One line, or null when the Task does not recur (or an older server did not say). */
-function recurrenceOutcomeLine(outcome) {
+function recurrenceOutcomeLine(outcome, taskRef, bin = 'skrr') {
     if (!outcome || typeof outcome !== 'object')
         return null;
     switch (outcome.state) {
@@ -22,8 +41,13 @@ function recurrenceOutcomeLine(outcome) {
             return 'Recurrence: the series is paused, so no next occurrence was scheduled.';
         case 'routine_managed':
             return 'Recurrence: a Routine owns this series, so no next occurrence was scheduled here.';
-        case 'not_armed':
-            return 'Recurrence: the series is live but no next occurrence was scheduled; check it with `tasks show`.';
+        case 'not_armed': {
+            const code = outcome.armFailure?.code;
+            const why = typeof code === 'string' && code
+                ? `${(0, data_provider_1.describeRecurrenceArmFailure)(code)} (${code})`
+                : 'The series is live but no next occurrence was scheduled.';
+            return `Recurrence: ${why} ${recurrenceRearmHint(code, taskRef, bin)}`;
+        }
         default:
             return null;
     }

package/dist/lib/tasks.d.ts

@@ -241,6 +241,45 @@ export declare function findTaskByExternalKey({ externalKey, spaceId, goalId, pa
     task: TaskRecord | null;
     duplicates: TaskRecord[];
 }>;
+export type ExternalKeyLookup = {
+    externalKey: string;
+    spaceId?: unknown;
+    goalId?: unknown;
+};
+export type ExternalKeyHit = {
+    task: TaskRecord | null;
+    duplicates: TaskRecord[];
+    /** Set when the lookup itself failed: "could not look" is not "nothing there". */
+    error?: Error;
+};
+/** The identity of one lookup: a key means a task only within its scope. */
+export declare function externalKeyLookupId(lookup: ExternalKeyLookup): string;
+/**
+ * Which of these tasks already exist? Answers for many keys at once.
+ *
+ * `create-tree`, `--resume` and `--verify` all start by asking that of every node
+ * of a tree, and asked it once per node, one after another: 94 round trips
+ * before the first write (OSK-S-440 #3). Two things bring that down without
+ * changing a single answer:
+ *
+ *   - Keys that share a prefix (`aap/c1`, `aap/c2`, ... — a tree is written
+ *     under one) are answered by ONE paged read of the prefix, per scope. The
+ *     read can return rows that are not this tree's; they are ignored, since a
+ *     key is matched whole. If the prefix is broad enough that the read hits its
+ *     page cap, whatever it did not find is looked up directly, because absence
+ *     from a truncated read proves nothing.
+ *   - Whatever is left is looked up by exact key, a few at a time rather than
+ *     one at a time.
+ *
+ * A server that predates `externalKeyPrefix` ignores it and returns the scope's
+ * tasks: still correct (matched whole), merely a wider read, and bounded by the
+ * same cap.
+ */
+export declare function findTasksByExternalKeys(lookups: readonly ExternalKeyLookup[], opts?: {
+    concurrency?: number;
+    minKeysForPrefix?: number;
+    maxPages?: number;
+}): Promise<Map<string, ExternalKeyHit>>;
 /**
  * What the CLI reports under `defaultAgent` in `--json` output.
  *