@wirecat/cli-core 0.555.0 → 0.557.0

package/dist/entities/task-results.d.ts

@@ -587,3 +587,75 @@ export declare const taskScan: v.StrictObjectSchema<{
         readonly category: v.NullableSchema<v.StringSchema<undefined>, undefined>;
     }, undefined>, undefined>;
 }, undefined>;
+export declare const taskAnalysisMark: v.StrictObjectSchema<{
+    readonly chat: v.StringSchema<undefined>;
+    readonly from: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+    readonly through: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+    readonly through_id: v.StringSchema<undefined>;
+    readonly by: v.StringSchema<undefined>;
+    readonly checked_at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+    readonly checked_through: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+    readonly at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+}, undefined>;
+export declare const taskAnalysisMarkMoved: v.StrictObjectSchema<{
+    readonly chat: v.StringSchema<undefined>;
+    readonly from: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+    readonly through: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+    readonly through_id: v.StringSchema<undefined>;
+    readonly by: v.StringSchema<undefined>;
+    readonly checked_at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+    readonly checked_through: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+    readonly at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+    readonly moved: v.BooleanSchema<undefined>;
+}, undefined>;
+export declare const taskAnalysis: v.StrictObjectSchema<{
+    readonly chat: v.StringSchema<undefined>;
+    readonly title: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly kind: v.StringSchema<undefined>;
+    readonly newest_at: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
+    readonly mark: v.NullableSchema<v.StrictObjectSchema<{
+        readonly chat: v.StringSchema<undefined>;
+        readonly from: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+        readonly through: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+        readonly through_id: v.StringSchema<undefined>;
+        readonly by: v.StringSchema<undefined>;
+        readonly checked_at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+        readonly checked_through: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+        readonly at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+    }, undefined>, undefined>;
+    readonly waiting: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly late: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly untrusted: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
+}, undefined>;
+export declare const taskReview: v.StrictObjectSchema<{
+    readonly chat: v.StringSchema<undefined>;
+    readonly from: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+    readonly mark: v.NullableSchema<v.StrictObjectSchema<{
+        readonly chat: v.StringSchema<undefined>;
+        readonly from: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+        readonly through: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+        readonly through_id: v.StringSchema<undefined>;
+        readonly by: v.StringSchema<undefined>;
+        readonly checked_at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+        readonly checked_through: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+        readonly at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+    }, undefined>, undefined>;
+    readonly late: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly has_more: v.BooleanSchema<undefined>;
+    readonly through: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>, undefined>;
+    readonly messages: v.ArraySchema<v.StrictObjectSchema<{
+        readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
+        readonly at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
+        readonly sender: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly outgoing: v.BooleanSchema<undefined>;
+        readonly reply_to: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly text: v.StringSchema<undefined>;
+    }, undefined>, undefined>;
+    readonly open_tasks: v.ArraySchema<v.StrictObjectSchema<{
+        readonly key: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly kind: v.StringSchema<undefined>;
+        readonly title: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly source: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, undefined>;
+    readonly untrusted: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>;
+}, undefined>;

package/dist/entities/task-results.js

@@ -2,7 +2,7 @@ import * as v from "valibot";
 import { TASK_TYPES } from "../domain/knowledge.js";
 import { LINK_KINDS, LINK_SOURCES } from "../store/sqlite/link-kinds.js";
 import { PRIORITY_LABELS, TASK_KINDS, TASK_ORIGINS, TASK_STATES, TASK_VERDICTS } from "../tasks/index.js";
-import { count, id, reference, text, time } from "./fields.js";
+import { count, id, reference, text, time, untrusted } from "./fields.js";
 import { closeSuggestion } from "./task.js";
 import { taskPair } from "./task-pair.js";
 const nullableTime = v.nullable(time);
@@ -135,3 +135,42 @@ export const taskScan = v.strictObject({
     held_chats: v.optional(count),
     tasks: v.array(v.strictObject({ source: text, kind: v.picklist(TASK_KINDS), category: v.nullable(text) })),
 });
+export const taskAnalysisMark = v.strictObject({
+    chat: text,
+    from: time,
+    through: time,
+    through_id: text,
+    by: text,
+    checked_at: time,
+    checked_through: time,
+    at: time,
+});
+export const taskAnalysisMarkMoved = v.strictObject({ ...taskAnalysisMark.entries, moved: v.boolean() });
+export const taskAnalysis = v.strictObject({
+    chat: text,
+    title: v.nullable(text),
+    kind: text,
+    newest_at: nullableTime,
+    mark: v.nullable(taskAnalysisMark),
+    waiting: count,
+    late: count,
+    untrusted,
+});
+export const taskReview = v.strictObject({
+    chat: text,
+    from: time,
+    mark: v.nullable(taskAnalysisMark),
+    late: count,
+    has_more: v.boolean(),
+    through: v.nullable(reference),
+    messages: v.array(v.strictObject({
+        ref: reference,
+        at: time,
+        sender: v.nullable(text),
+        outgoing: v.boolean(),
+        reply_to: v.nullable(text),
+        text,
+    })),
+    open_tasks: v.array(v.strictObject({ key: v.nullable(text), kind: text, title: v.nullable(text), source: v.nullable(text) })),
+    untrusted,
+});

package/dist/errors/reasons.d.ts

@@ -7,7 +7,7 @@ export declare const REASONS: ErrorReason[];
  * Detail keys an error from this package may carry, until each is registered on its own reason. Not `cause`:
  * that can hold a provider's or SQLite's raw text.
  */
-export declare const DETAILS: readonly ["contracts", "calendars", "allowed", "alternative", "arguments", "at", "available", "batch", "budget", "built", "candidates", "chat", "chat_id", "cli", "complete", "emitted_bytes", "exact", "forum", "guide", "hint", "id", "index", "kind", "limit", "limit_source", "max_bytes", "model", "name", "operation_id", "operation_ids", "text_limit", "store_refused_in", "subtasks", "partial_output", "parent", "path", "permission", "person_ids", "previous_chat_id", "profiles", "provider_error", "provider", "recovery", "reference", "remembered", "retry_at", "retry_after_ms", "runtime", "saved", "scheduled_for", "script", "sent", "sent_count", "settlement_failed", "span", "sqlite", "stage", "standing", "state", "stderr", "term", "total", "upgraded", "wanted"];
+export declare const DETAILS: readonly ["contracts", "calendars", "allowed", "alternative", "arguments", "at", "available", "batch", "budget", "built", "candidates", "chat", "chat_id", "cli", "column", "complete", "emitted_bytes", "exact", "file", "forum", "guide", "hint", "id", "index", "kind", "limit", "limit_source", "line", "max_bytes", "model", "name", "operation_id", "operation_ids", "text_limit", "store_refused_in", "subtasks", "partial_output", "parent", "path", "permission", "person_ids", "previous_chat_id", "profiles", "provider_error", "provider", "recovery", "reference", "remembered", "retry_at", "retry_after_ms", "runtime", "saved", "scheduled_for", "script", "sent", "sent_count", "settlement_failed", "span", "sqlite", "stage", "standing", "state", "stderr", "term", "total", "upgraded", "wanted"];
 /** What a CLI adds to the shared registry: its own reasons, and the detail keys its adapters raise. */
 export interface AppErrors {
     reasons?: readonly ErrorReason[];

package/dist/errors/reasons.js

@@ -57,6 +57,11 @@ const OTHERS = [
     validation("push.too-many-files", "the folder holds more files than one push takes"),
     validation("push.unreadable", "the folder to push could not be read"),
     validation("spreadsheet.unreadable", "the workbook could not be read"),
+    [
+        "config.unrepairable",
+        "configuration_error",
+        "the settings file's damage has more than one reading; nothing was changed, so it is fixed by hand",
+    ],
     ["state.invalid", "configuration_error", "the saved sync state is unreadable or invalid; it is kept, not reset"],
     ["sync.partial", "provider_error", "some calendars did not sync; the next sync retries them"],
     validation("event.conflict", "the event changed at the provider since the last sync; sync and try again"),
@@ -133,8 +138,23 @@ const OTHERS = [
     validation("input.required", "the command needs an answer and cannot ask for one"),
     validation("input.too-large", "the input is over its size limit"),
     ["meeting-project.stale", "configuration_error", "the meeting's project changed meanwhile"],
+    validation("finance.allocate", "the invoice or payment cannot take an allocation in its state"),
+    validation("finance.currency", "the payment and the invoice are in different currencies; nothing is converted"),
+    validation("finance.field", "a field of the invoice or payment is not valid"),
+    validation("finance.line-amount", "the line's amount is not its quantity times its unit price"),
+    validation("finance.lines", "the invoice's lines are not valid"),
+    validation("finance.over-invoice", "the allocation would settle more than the invoice's total"),
+    validation("finance.over-payment", "the allocation would use more than the payment's amount"),
+    ["finance.owner-only", "permission_error", "only the owner does this with money"],
+    validation("finance.party", "a party is a person: or organization: reference"),
+    validation("finance.ref", "the reference names no invoice or payment"),
+    validation("finance.status", "the invoice's status does not allow this"),
+    validation("finance.total", "the invoice's total is not the sum of its lines"),
     validation("memory.evidence-required", "a memory needs its evidence"),
     validation("memory.scope-required", "a memory needs its scope"),
+    validation("money.amount", "the amount is not a decimal string in the currency's scale"),
+    validation("money.currency", "the currency is not one the store keeps money in"),
+    validation("money.quantity", "the quantity is not a decimal above 0"),
     ["model.not-downloaded", "not_found", "the model is not downloaded on this machine"],
     ["person.no-owner", "not_found", "no person is marked as the owner in the store"],
     ["transcription.no-key", "authentication_error", "no OpenAI key is set for transcription"],
@@ -188,6 +208,7 @@ const OTHERS = [
     validation("task.has-subtasks", "the task has subtasks; move or detach them before it moves to another project"),
     validation("task.is-subtask", "a subtask moves to another project only when it is detached from its parent in the same write"),
     validation("task.duplicate-candidates", "open tasks may be the same job: attach to one, or add it as new"),
+    validation("task.already-read", "the message was already read for tasks: a read again only updates and closes tasks unless --open-new"),
     validation("task.certainty-required", "an agent closes a task with its certainty, 0 to 1"),
     ["task.pair-decided", "permission_error", "the owner already decided the pair; an agent does not change it"],
     validation("task.no-close-suggestion", "the task has no agent's close waiting on the owner"),
@@ -245,9 +266,11 @@ export const DETAILS = [
     "chat",
     "chat_id",
     "cli",
+    "column",
     "complete",
     "emitted_bytes",
     "exact",
+    "file",
     "forum",
     "guide",
     "hint",
@@ -256,6 +279,7 @@ export const DETAILS = [
     "kind",
     "limit",
     "limit_source",
+    "line",
     "max_bytes",
     "model",
     "name",

package/dist/index.d.ts

@@ -1,12 +1,14 @@
 export { bareCheck, type CheckWords, checkWords } from "./domain/checks.js";
 export type { CounterField, CounterObservation, CounterObservations, CounterState } from "./domain/counters.js";
 export { COUNTER_FIELDS, counterValue, observedCounters } from "./domain/counters.js";
+export { FINANCE_REVIEWS, type FinanceReview, INVOICE_DIRECTIONS, INVOICE_STATUSES, type InvoiceDirection, type InvoiceStatus, MONEY_DIRECTIONS, type MoneyDirection, } from "./domain/finance.js";
 export { type FormattedText, type HtmlFormatting, type MarkdownFormatting, type TextSpan, validateFormattedText, } from "./domain/formatting.js";
 export { formatLocator, isLocator, type MessageLocator, parseLocator } from "./domain/locator.js";
 export { type Markup, parseMarkdown } from "./domain/markdown.js";
 export { parseMarkdownSpans } from "./domain/markdown-spans.js";
 export type { MessageLink, MessagePermalink } from "./domain/message-link.js";
 export type * from "./domain/models.js";
+export { CURRENCY_SCALES, currencyOf, type Money, minorUnits, moneyLabel, moneyOf, } from "./domain/money.js";
 export { countedPoll } from "./domain/polls.js";
 export { FOLDER_PROVIDERS, isFolderProvider, isKind, KINDS, type Kind, kindIn, kindOf, PROVIDERS, type ProviderEntry, providerNamed, providers, UNKNOWN_PROVIDER, useProviders, } from "./domain/providers.js";
 export type { RankingGraphEvidence, RankingGraphLink } from "./domain/rankings-graph.js";

package/dist/index.js

@@ -1,9 +1,11 @@
 export { bareCheck, checkWords } from "./domain/checks.js";
 export { COUNTER_FIELDS, counterValue, observedCounters } from "./domain/counters.js";
+export { FINANCE_REVIEWS, INVOICE_DIRECTIONS, INVOICE_STATUSES, MONEY_DIRECTIONS, } from "./domain/finance.js";
 export { validateFormattedText, } from "./domain/formatting.js";
 export { formatLocator, isLocator, parseLocator } from "./domain/locator.js";
 export { parseMarkdown } from "./domain/markdown.js";
 export { parseMarkdownSpans } from "./domain/markdown-spans.js";
+export { CURRENCY_SCALES, currencyOf, minorUnits, moneyLabel, moneyOf, } from "./domain/money.js";
 export { countedPoll } from "./domain/polls.js";
 export { FOLDER_PROVIDERS, isFolderProvider, isKind, KINDS, kindIn, kindOf, PROVIDERS, providerNamed, providers, UNKNOWN_PROVIDER, useProviders, } from "./domain/providers.js";
 export { rankingOptions } from "./domain/rankings-options.js";

package/dist/mail/cli/index.d.ts

@@ -2,6 +2,7 @@ import { Command } from "commander";
 import { type MailServerAccess } from "../../mail/server-search.js";
 import type { AppIdentity } from "../../ports/app.js";
 import { type AccountKey, type MessageStore } from "../../store/store.js";
+export { mailMark, markItem, markText } from "./marks.js";
 export { MAIL_REVIEW_QUERY, MAIL_REVIEW_STEPS } from "./review.js";
 /** What a mail CLI hands the shared commands: how to open the store for one run, and whose mail it reads. */
 export interface MailReads {

package/dist/mail/cli/index.js

@@ -18,7 +18,9 @@ import { searchMailServer } from "../../mail/server-search.js";
 import { atDetail } from "../../output-detail.js";
 import { sourceKey } from "../../services/server-search.js";
 import { queryFilter, THREAD_COLUMNS } from "../../store/store.js";
+import { acknowledgeCommand } from "./marks.js";
 import { mailReviewCommand } from "./review.js";
+export { mailMark, markItem, markText } from "./marks.js";
 export { MAIL_REVIEW_QUERY, MAIL_REVIEW_STEPS } from "./review.js";
 /** A locked or broken store must fail the command, not read as "nothing stored yet". */
 const absentAccount = (error) => {
@@ -226,6 +228,7 @@ const messagesCommand = (mail) => {
             ? listOf("messages show", { items: shown, limit: Math.max(1, shown.length), has_more: false })
             : itemOf(shown.find((_, at) => emails[at]?.anchor) ?? shown[0]), () => shownText(emails));
     });
+    messages.addCommand(acknowledgeCommand(mail));
     return messages;
 };
 const mailThread = v.strictObject({

package/dist/mail/cli/marks.d.ts

@@ -0,0 +1,26 @@
+import { Command } from "commander";
+import * as v from "valibot";
+import { type MailMark } from "../marks.js";
+import type { MailReads } from "./index.js";
+/** A holder's mark as `--json`, `mail status` and MCP show it. */
+export declare const mailMark: v.StrictObjectSchema<{
+    readonly holder: v.StringSchema<undefined>;
+    readonly through_id: v.NumberSchema<undefined>;
+    readonly through_received_at: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly held: v.NumberSchema<undefined>;
+    readonly read: v.NumberSchema<undefined>;
+    readonly skipped: v.StrictObjectSchema<{
+        readonly bulk: v.NumberSchema<undefined>;
+        readonly envelope: v.NumberSchema<undefined>;
+        readonly partial: v.NumberSchema<undefined>;
+        readonly draft: v.NumberSchema<undefined>;
+    }, undefined>;
+    readonly updated_at: v.StringSchema<undefined>;
+}, undefined>;
+export declare const markItem: (mark: MailMark) => v.InferOutput<typeof mailMark>;
+export declare const markText: (mark: MailMark) => string;
+/**
+ * `messages acknowledge`: a holder says it is done with what `review --holder` gave it, and its mark moves there. It
+ * only moves the holder's own bookkeeping forward, so a read-only scheduled run may do it.
+ */
+export declare const acknowledgeCommand: (mail: MailReads) => Command;

package/dist/mail/cli/marks.js

@@ -0,0 +1,51 @@
+import { annotate } from "@wirecat/cli-base/commands";
+import { Command } from "commander";
+import * as v from "valibot";
+import { answerEntity } from "../../cli/answer-entity.js";
+import { outputFor } from "../../cli/context.js";
+import { destroysNothing, LOCAL_WRITE } from "../../cli/effects.js";
+import { itemOf, renderAnswer } from "../../cli/envelope.js";
+import { acknowledgeMark } from "../marks.js";
+const iso = (ms) => (ms === null ? null : new Date(ms).toISOString());
+/** A holder's mark as `--json`, `mail status` and MCP show it. */
+export const mailMark = v.strictObject({
+    holder: v.string(),
+    through_id: v.number(),
+    through_received_at: v.nullable(v.string()),
+    held: v.number(),
+    read: v.number(),
+    skipped: v.strictObject({ bulk: v.number(), envelope: v.number(), partial: v.number(), draft: v.number() }),
+    updated_at: v.string(),
+});
+export const markItem = (mark) => ({
+    holder: mark.holder,
+    through_id: mark.throughId,
+    through_received_at: iso(mark.throughAt),
+    held: mark.held.length,
+    read: mark.read,
+    skipped: mark.skipped,
+    updated_at: iso(mark.updatedAt),
+});
+export const markText = (mark) => `${mark.holder}  through ${mark.throughId}${mark.throughAt === null ? "" : ` (${iso(mark.throughAt)})`}  ` +
+    `read ${mark.read}  held ${mark.held.length}  skipped bulk ${mark.skipped.bulk}, envelope ${mark.skipped.envelope}, ` +
+    `partial ${mark.skipped.partial}, draft ${mark.skipped.draft}  updated ${iso(mark.updatedAt)}\n`;
+/**
+ * `messages acknowledge`: a holder says it is done with what `review --holder` gave it, and its mark moves there. It
+ * only moves the holder's own bookkeeping forward, so a read-only scheduled run may do it.
+ */
+export const acknowledgeCommand = (mail) => answerEntity(destroysNothing(annotate(new Command("acknowledge"), {
+    effects: LOCAL_WRITE,
+    examples: [
+        `${mail.app.command} personal messages acknowledge --holder mail-triage --cursor 9123.1762090000000`,
+    ],
+})), "mail_mark", mailMark)
+    .summary("move a holder's processing mark to what it has read")
+    .description("record that a holder — an agent or a pipeline — processed the mail `review --holder` gave it, with the cursor " +
+    "that review gave; the mark only moves forward, and mail still partial waits for the next review")
+    .requiredOption("--holder <name>", "whose mark: lower-case letters, digits and dashes, such as mail-triage")
+    .requiredOption("--cursor <cursor>", "the cursor `review --holder` gave")
+    .action(async function () {
+    const { holder, cursor } = this.opts();
+    const mark = await mail.read(this, (store, mailbox) => acknowledgeMark(store, mailbox, holder, cursor));
+    renderAnswer(this, outputFor(this), itemOf(markItem(mark)), () => markText(mark));
+});

package/dist/mail/cli/review.js

@@ -16,6 +16,7 @@ import { parseDuration } from "../../domain/duration.js";
 import { formatReference } from "../../domain/references.js";
 import { AGENDA_DEFAULTS } from "../../services/agenda.js";
 import { REVIEW_DAYS, reviewStart } from "../../services/inbox.js";
+import { readPastMark } from "../marks.js";
 import { hitText } from "../read.js";
 import { OWED_DAYS, REVIEW_THREADS, reviewMail } from "../review.js";
 const DAY = 86_400_000;
@@ -30,6 +31,15 @@ export const MAIL_REVIEW_QUERY = defineQuery({
 });
 /** The mail review's steps; a host lists them beside its own so its step checks know them. */
 export const MAIL_REVIEW_STEPS = defineSteps([
+    {
+        id: "mail-messages.acknowledge",
+        command: "messages acknowledge",
+        args: [
+            { name: "holder", required: true },
+            { name: "cursor", required: true },
+        ],
+        why: "once these are processed, this moves the holder's mark past them",
+    },
     {
         id: "mail-review.next",
         command: "review",
@@ -113,6 +123,62 @@ const reviewAnswer = (found, mailbox, fresh) => {
         meta: found.complete ? {} : { complete: false },
     });
 };
+const holderReview = async (command, mail, holder, query) => {
+    const { unanswered, waiting } = command.opts();
+    if (typedQuery(query).trim() || unanswered !== undefined || waiting !== undefined)
+        throw new CliError("validation_error", "--holder reads past its own mark — not with a query, --unanswered or --waiting");
+    const { read, mailbox, marks } = await mail.read(command, async (store, mailbox) => {
+        const read = await readPastMark(store, mailbox, holder);
+        const account = read.emails.length ? await store.accounts.storedAccount(mailbox) : undefined;
+        const marks = account
+            ? await store.mail.emailMarks(account.id, read.emails.map((one) => one.id))
+            : new Map();
+        return { read, mailbox, marks };
+    });
+    const chats = new Map();
+    for (const email of read.emails) {
+        const chat = chats.get(email.chatId) ?? {
+            id: email.chatId,
+            title: email.chatTitle,
+            kind: "dialog",
+            messages: [],
+            more: false,
+        };
+        const mark = marks.get(email.id);
+        chat.messages.push(mark ? { ...email, marks: mark } : email);
+        chats.set(email.chatId, chat);
+    }
+    const now = new Date().toISOString();
+    const found = {
+        since: read.mark?.throughAt ? new Date(read.mark.throughAt).toISOString() : now,
+        until: now,
+        complete: !read.more,
+        chats: [...chats.values()],
+        skipped: [],
+        partial: false,
+        quiet: 0,
+    };
+    const answer = reviewAnswer(found, mailbox, true);
+    const skipped = Object.entries(read.skipped).filter(([, count]) => count > 0);
+    answer.next = [
+        stepOf(step("mail-messages.acknowledge"), { args: { holder, cursor: read.cursor } }),
+        ...(answer.next ?? []),
+    ];
+    answer.missing = [
+        ...(answer.missing ?? []),
+        ...(read.held > 0 ? [{ field: "items", why: `${read.held} partial emails held until they are whole` }] : []),
+        ...(skipped.length
+            ? [{ field: "items", why: `left out: ${skipped.map(([reason, count]) => `${count} ${reason}`).join(", ")}` }]
+            : []),
+    ];
+    const output = outputFor(command);
+    renderAnswer(command, output, answer, () => {
+        output.renderer.note(read.mark
+            ? `${holder}: past ${read.mark.throughId}; acknowledge with --cursor ${read.cursor}${read.more ? "; more after these" : ""}`
+            : `${holder} has no mark yet: it starts from now — acknowledge with --cursor ${read.cursor}`);
+        return read.emails.map((hit) => `${hitText(hit)}${markText(marks.get(hit.id))}\n`).join("");
+    });
+};
 /**
  * `review` over the stored mail of the profile's mailbox, with tg's words: what is new, what the owner owes, what
  * waits for an answer. It reads the store only and opens no task.
@@ -122,7 +188,6 @@ export const mailReviewCommand = (mail) => annotate(new Command("review"), {
         `${mail.app.command} personal review "date>2h"`,
         `${mail.app.command} personal review --new`,
         `${mail.app.command} personal review --unanswered 1d`,
-        `${mail.app.command} personal review --waiting 7d`,
     ],
     effects: LOCAL_READ,
     partial: true,
@@ -136,6 +201,8 @@ export const mailReviewCommand = (mail) => annotate(new Command("review"), {
     .argument("[query...]", `where the last review ended: date>2h; ${REVIEW_DAYS} days ago if no date`)
     .option("--unanswered [duration]", "only threads whose newest email came to you, in To or Cc, with no answer for this long — 4h, 1d; 24h if not given")
     .option("--waiting [duration]", "only threads where you wrote last and nobody answered for this long — 3d; 7d if not given")
+    .option("--holder <name>", "read for this holder — an agent or a pipeline — what is stored past its processing mark, by store order; " +
+    "bulk, envelopes, drafts and partial mail left out; `messages acknowledge` moves the mark")
     .option("--new", "what changed since the last `review --new` of this mailbox, a point per thread — for scheduled runs")
     .addHelpText("after", `
 Without a date, --unanswered and --waiting look at threads active in the last ${OWED_DAYS} days.
@@ -145,6 +212,8 @@ Mail newer than the last finished sync waits for the next review. Each reader ke
 an agent over MCP, and each scheduled run.`)
     .action(async function (query) {
     const options = this.opts();
+    if (options.holder !== undefined)
+        return holderReview(this, mail, options.holder, query);
     const { since: from, meta } = catchUpQuery(query, MAIL_REVIEW_QUERY, "review");
     const bulk = nativeTerms(listQuery(typedQuery(query), MAIL_REVIEW_QUERY, "review"), "review").get("bulk")?.value;
     if (bulk !== undefined && bulk !== "false")

package/dist/mail/index.d.ts

@@ -6,6 +6,7 @@ export { dropMissing, type Gone, tooManyGone } from "./gone.js";
 export { type AuthVerdicts, HEADER_FIELDS, headersOf, type MailHeaders, mailHeadersOf } from "./headers.js";
 export { type MailIdsInput, mailIds } from "./ids.js";
 export { decodedLabelName, decodeMailboxName, labelName, systemLabel } from "./labels.js";
+export { acknowledgeMark, cursorOf, HOLD_PARTIAL_MS, HOLDER, MARK_BATCH, type MailMark, type MarkRead, markOf, marksOf, readPastMark, type SkipReason, } from "./marks.js";
 export { type MailTurn, mailTurn } from "./owed.js";
 export { type Address, htmlToText, looksLikeHtml, MAX_ATTACHMENTS, MAX_BODY_CHARS, type ParsedMail, parseMail, } from "./parse.js";
 export { PARTIAL, type PartialOutcome } from "./partial.js";

package/dist/mail/index.js

@@ -6,6 +6,7 @@ export { dropMissing, tooManyGone } from "./gone.js";
 export { HEADER_FIELDS, headersOf, mailHeadersOf } from "./headers.js";
 export { mailIds } from "./ids.js";
 export { decodedLabelName, decodeMailboxName, labelName, systemLabel } from "./labels.js";
+export { acknowledgeMark, cursorOf, HOLD_PARTIAL_MS, HOLDER, MARK_BATCH, markOf, marksOf, readPastMark, } from "./marks.js";
 export { mailTurn } from "./owed.js";
 export { htmlToText, looksLikeHtml, MAX_ATTACHMENTS, MAX_BODY_CHARS, parseMail, } from "./parse.js";
 export { PARTIAL } from "./partial.js";

package/dist/mail/marks.d.ts

@@ -0,0 +1,56 @@
+import type { AccountKey, MessageStore, StoredHit } from "../store/store.js";
+/** A holder's name: what `--holder` takes and the mark's key ends with. */
+export declare const HOLDER: RegExp;
+/** At most this many emails are read past the mark in one go; the rest come with the next read. */
+export declare const MARK_BATCH = 200;
+/** A partial email waits this long to be stored whole, then is skipped. */
+export declare const HOLD_PARTIAL_MS: number;
+export type SkipReason = "bulk" | "envelope" | "partial" | "draft";
+/**
+ * How far one holder — an agent, a pipeline — has processed an account's mail, in the shared store (`sync_cursors`,
+ * key `consumer:<holder>`). It counts by the store's insert order (`emails.id`), so mail stored late, older than what
+ * was read, is still after the mark. Partial emails are held until they are whole.
+ */
+export interface MailMark {
+    holder: string;
+    throughId: number;
+    /** ms: when the email at `throughId` was received; for display. */
+    throughAt: number | null;
+    held: number[];
+    read: number;
+    skipped: Record<SkipReason, number>;
+    /** ms. */
+    updatedAt: number;
+}
+export declare const markOf: (store: MessageStore, mailbox: AccountKey, holder: string) => Promise<MailMark | undefined>;
+/** Every holder's mark on the mailbox, by name. */
+export declare const marksOf: (store: MessageStore, mailbox: AccountKey) => Promise<MailMark[]>;
+/** The mark's state, as a cursor `acknowledge` takes back: the last id read, and when it was read. */
+export declare const cursorOf: (throughId: number, readAt: number) => string;
+export interface MarkRead {
+    /** The emails for the holder, oldest first; bulk, envelopes, drafts and partial mail left out. */
+    emails: StoredHit[];
+    /** What `acknowledge --cursor` takes once the holder is done with these. */
+    cursor: string;
+    /** More is stored after this batch: read again after acknowledging. */
+    more: boolean;
+    held: number;
+    skipped: Record<SkipReason, number>;
+    /** `undefined` before the holder's first acknowledge: it starts from the mail stored now. */
+    mark: MailMark | undefined;
+}
+/**
+ * What the holder has not processed: the emails stored after its mark, and the held ones that are whole now. Reads
+ * only; the mark moves when the holder acknowledges. A holder with no mark starts from now: its first read is
+ * empty and gives the cursor of the newest stored email.
+ */
+export declare const readPastMark: (store: MessageStore, mailbox: AccountKey, holder: string, { now, limit }?: {
+    now?: number;
+    limit?: number;
+}) => Promise<MarkRead>;
+/**
+ * Moves the holder's mark to the cursor its read gave, never back. An email whole when it was read counts read; one
+ * still partial, or changed after the read (it may have become whole since), is held and comes with the next read.
+ * The same cursor twice changes nothing more.
+ */
+export declare const acknowledgeMark: (store: MessageStore, mailbox: AccountKey, holder: string, cursor: string, now?: number) => Promise<MailMark>;