@wirecat/cli-core 0.593.0 → 0.595.0

package/CHANGELOG.md

@@ -7,6 +7,57 @@ shape of this file.
 
 ## Unreleased
 
+## 0.595.0 — 06.11.2026
+
+### Added
+
+- **A rollback copy before a breaking store upgrade.** Before a migration that raises `min_compatible` (after which
+  older tools refuse the store), the base tables it names are copied into `backups/` beside the store, as
+  `<store>-rollback-schema-<version>-<time>.db`, with the schema as it was. Search indexes, vectors and other derived
+  tables are never copied. Without the free space for it, the upgrade runs anyway and warns. `store restore <copy>`
+  puts the tables back and returns the store to that version, so the older tool opens it again; its `store rebuild`
+  then refreshes the search indexes. The copy is deleted on the first open a day after the upgrade succeeded.
+- **`Migration.tables`** and the manifest's `tables`: required on a migration that raises `minCompatible`, the base
+  tables it changes by their names before it. `generatedMigrations` refuses a raising one without it, or one that
+  names a derived table.
+
+## 0.594.0 — 06.11.2026
+
+### Added
+
+- **A CRM write port, `CrmWriter`** (`@wirecat/cli-core/crm`), beside `CrmSource`: `create`, `update`, `move`,
+  `close` and `remove` of deals and leads, each sent once with its `operationId` and answering the whole item as the
+  CRM holds it. `capabilities` names the kinds and verbs it takes and whether it recognises a repeated operation id
+  (Bitrix24's `Idempotency-Key`). Fields use `CrmItem`'s names, plus `owner` (a CRM user's id) and `custom` (the CRM's
+  own fields by code). An adapter refuses a custom code that is a neutral field under another name, such as a stage
+  or an owner. `CRM_WRITE_DEFAULTS` and `CRM_WRITE_KEYS` go into a CLI's `commandPermissions`.
+- **`deals` and `leads` `create`, `update`, `move`, `close` and `delete`** in `addCrmCommands`, mounted by its new
+  `writes` option (the writer's capabilities) and run through `CrmRun.writes`. Each goes through the write guard and
+  the send journal, honours `--dry-run`, and is exposed over MCP as a write. A write is never sent twice: a lost
+  answer is `outcome_unknown`, and `--operation-id` is offered only by a CRM that recognises a repeat. A stage in
+  `create` or `update` also checks the `move` key, and a won or lost stage the `close` key. An owner other than the
+  sign-in's own user (`CrmWrites.self`) checks `crm.assign-others`, denied by default. `delete` asks by default. The
+  item the CRM answers is stored as a sync would store it, and the answer carries it with its `operation_id`.
+  `--field <key=value>` sets a custom field; an empty value clears it.
+- **`crmWriteContract` and a write side on `fakeCrmSource`** (`@wirecat/cli-core/crm/testing`). The contract checks
+  that an update of one field answers the whole item, that a custom code naming a neutral field is refused before
+  anything is sent, and that a lost answer ends after one request.
+- **`CrmItem.closedReason`** is stored as the deal's or lead's `closed_reason`, and `store.crm.refOf` finds the stored
+  copy of a CRM id.
+- **A CRM's deal and lead pipelines may share an id (store version 53).** The unique key of a CRM account's pipelines
+  is now its account, kind and id, so `savePipelines` stores a lead pipeline whose id a deal pipeline already has,
+  and `crmSourceContract` checks pipeline ids are unique within each kind only.
+- **Pipelines and stages the CRM no longer lists are marked deleted (store version 53),** never removed: deals may still
+  stand in them. `savePipelines` takes a kind's whole list, marks what it lacks and brings back what it lists again; an
+  empty list marks nothing. A deleted pipeline is left out of `pipelines()` and of a lookup by name, and still found by
+  its `pipeline:<id>`. A deleted stage is only marked. The migration adds columns and swaps one index; `minCompatible`
+  stays 34.
+
+### Removed
+
+- **The `crm.pipeline-clash` skip reason.** `savePipelines` no longer skips a pipeline for sharing the other kind's id,
+  so `CrmSkipped.reason` is `crm.stage-unknown` or `crm.item-invalid`.
+
 ## 0.593.0 — 06.11.2026
 
 ### Added

package/dist/background/schedules.d.ts

@@ -49,6 +49,14 @@ export interface DaySpend {
 export declare const localDay: (at: Date) => string;
 /** What the schedule's runs cost today; nothing before its first priced run of the day. */
 export declare const spentToday: (file: string, now?: Date) => number;
+/**
+ * What an agent is given on its stdin before its first turn: the host's own reads of what the run is about, so
+ * the agent spends no model turns fetching them. Returns `undefined` when the schedule has none. `run` runs one
+ * command of this CLI under the run's variables and answers its stdout.
+ */
+export type AgentInput = (schedule: Schedule, run: (argv: string[]) => Promise<string>) => Promise<string | undefined>;
+/** The most an agent's input may hold; a longer one is cut, so a mailbox in flood cannot grow every turn's context. */
+export declare const AGENT_INPUT_MAX_CHARS = 60000;
 /** Another CLI a scheduled agent may run by name, as the host declares it: `memo`'s agent runs `mail`. */
 export type AgentCli = Pick<AppIdentity, "command" | "appName" | "envPrefix">;
 export interface LastRun {
@@ -164,7 +172,7 @@ export declare const CREDENTIALS_UNREACHABLE = "credentials.unreachable";
  * keyring, so a run that fails for that reason is tried again, a minute then up to 15 minutes apart, for up to
  * 12 hours. A schedule that repeats every few minutes is left to its next tick; a run by hand fails at once.
  */
-export declare const runSchedule: (app: AppIdentity, system: ServerSystem, env: NodeJS.ProcessEnv, file: string, { now, timer, signal, killAfterMs, untilUnlocked, wait, agentRuns, }?: {
+export declare const runSchedule: (app: AppIdentity, system: ServerSystem, env: NodeJS.ProcessEnv, file: string, { now, timer, signal, killAfterMs, untilUnlocked, wait, agentRuns, agentInput, }?: {
     now?: () => Date;
     timer?: Timer;
     signal?: AbortSignal;
@@ -173,4 +181,5 @@ export declare const runSchedule: (app: AppIdentity, system: ServerSystem, env:
     wait?: (ms: number, signal?: AbortSignal) => Promise<void>;
     /** The other CLIs an agent may run; each runs under its own read-only lock and knows it runs from a schedule. */
     agentRuns?: readonly AgentCli[];
+    agentInput?: AgentInput;
 }) => Promise<LastRun>;

package/dist/background/schedules.js

@@ -53,6 +53,11 @@ const reportOf = (stdout) => {
         return { text: stdout };
     }
 };
+/** The most an agent's input may hold; a longer one is cut, so a mailbox in flood cannot grow every turn's context. */
+export const AGENT_INPUT_MAX_CHARS = 60_000;
+const capped = (input) => input.length <= AGENT_INPUT_MAX_CHARS
+    ? input
+    : `${input.slice(0, AGENT_INPUT_MAX_CHARS)}\n\n[input cut at ${AGENT_INPUT_MAX_CHARS} characters; the rest waits for the next run]\n`;
 /** Why a timer left a run out, as an id a translation can key on; `why` stays the English sentence. */
 export const SKIP_REASONS = {
     costDayCap: "cost.day-cap",
@@ -426,7 +431,7 @@ const pause = (ms, signal) => new Promise((resolve) => {
  * keyring, so a run that fails for that reason is tried again, a minute then up to 15 minutes apart, for up to
  * 12 hours. A schedule that repeats every few minutes is left to its next tick; a run by hand fails at once.
  */
-export const runSchedule = async (app, system, env, file, { now = () => new Date(), timer, signal, killAfterMs = KILL_AFTER_MS, untilUnlocked = false, wait = pause, agentRuns = [], } = {}) => {
+export const runSchedule = async (app, system, env, file, { now = () => new Date(), timer, signal, killAfterMs = KILL_AFTER_MS, untilUnlocked = false, wait = pause, agentRuns = [], agentInput, } = {}) => {
     const schedule = readSchedule(file);
     const folder = join(file, "..");
     const runs = join(folder, "runs");
@@ -434,12 +439,24 @@ export const runSchedule = async (app, system, env, file, { now = () => new Date
     const agent = schedule.kind === "agent";
     const retries = untilUnlocked && !("every" in schedule.when);
     const firstAt = now().getTime();
-    let last = await attemptSchedule(app, system, env, schedule, folder, { now, signal, killAfterMs, agentRuns });
+    let last = await attemptSchedule(app, system, env, schedule, folder, {
+        now,
+        signal,
+        killAfterMs,
+        agentRuns,
+        agentInput,
+    });
     for (let delay = LOCKED_FIRST_WAIT_MS; retries && lockedOut(last) && !signal?.aborted && now().getTime() - firstAt + delay <= LOCKED_GIVE_UP_MS; delay = Math.min(delay * 2, LOCKED_LONGEST_WAIT_MS)) {
         await wait(delay, signal);
         if (signal?.aborted)
             break;
-        last = await attemptSchedule(app, system, env, schedule, folder, { now, signal, killAfterMs, agentRuns });
+        last = await attemptSchedule(app, system, env, schedule, folder, {
+            now,
+            signal,
+            killAfterMs,
+            agentRuns,
+            agentInput,
+        });
     }
     const { exitCode, output } = last;
     const errors = agent ? output.replace(/\.md$/, ".log") : output;
@@ -493,8 +510,24 @@ export const runSchedule = async (app, system, env, file, { now = () => new Date
     }
     return last;
 };
+/** The agent's input, or none: a host read that fails leaves the agent to fetch what it needs itself. */
+const inputOf = async (agentInput, system, env, schedule, log) => {
+    try {
+        const input = await agentInput(schedule, async (argv) => {
+            const ran = await system.run([...system.entry, ...argv], env);
+            if (ran.code !== 0)
+                throw new Error(`${argv.slice(0, 3).join(" ")} exited ${ran.code}`);
+            return ran.stdout;
+        });
+        return input === undefined ? undefined : capped(input);
+    }
+    catch (error) {
+        log.warn({ event: "schedule.input-failed", schedule: schedule.name, reason: String(error) });
+        return undefined;
+    }
+};
 /** One run of the schedule's command or agent: its output in `runs/`, its result in `last.json`. */
-const attemptSchedule = async (app, system, env, schedule, folder, { now, signal, killAfterMs, agentRuns, }) => {
+const attemptSchedule = async (app, system, env, schedule, folder, { now, signal, killAfterMs, agentRuns, agentInput, }) => {
     const runs = join(folder, "runs");
     const stamp = now()
         .toISOString()
@@ -526,9 +559,13 @@ const attemptSchedule = async (app, system, env, schedule, folder, { now, signal
     const facts = { schedule: schedule.name, kind: schedule.kind };
     const began = now().getTime();
     log.info({ event: "schedule.start", ...facts });
+    const input = agent && agentInput ? await inputOf(agentInput, system, childEnv, schedule, log) : undefined;
     let costUsd;
     const exitCode = await new Promise((resolve) => {
-        const child = spawn(program, args, { env: childEnv, cwd: folder, stdio: ["ignore", "pipe", "pipe"] });
+        const child = spawn(program, args, { env: childEnv, cwd: folder, stdio: ["pipe", "pipe", "pipe"] });
+        // An agent that stops reading its stdin may close it first; that is no failure of the run.
+        child.stdin?.on("error", () => { });
+        child.stdin?.end(input);
         const out = [];
         const err = [];
         child.stdout.on("data", (chunk) => out.push(chunk));

package/dist/cli/index.d.ts

@@ -1,5 +1,5 @@
 export { AI_ENTRIES, AI_SETTING_KEYS, type AISettings, resolveAISettings } from "../analysis/settings.js";
-export type { AgentCli } from "../background/schedules.js";
+export type { AgentCli, AgentInput } from "../background/schedules.js";
 export { parseDuration } from "../domain/duration.js";
 export { openOf, PROFILE_PLACEHOLDER, type ProfilesFor, type RefOpen, type RefSummary, refLabel, } from "../domain/ref-summaries.js";
 export { botTemplate } from "../entities/list-results.js";

package/dist/cli/messenger/store-maintenance-command.js

@@ -12,7 +12,7 @@ import { migrate } from "../../store/migrations.js";
 import { openCache } from "../../store/open.js";
 import { storePath } from "../../store/path.js";
 import { deleteCopy, repairStore } from "../../store/repair.js";
-import { drainNoteIndex, dropAllUnusedVectors, fillSearchIndex, fillStems, involvementStoreOver, noteIndexState, openSqlite, openStore, orphanPointers, pendingNormalization, resetAttachmentWords, resetNoteIndex, resetSearchIndex, resetStems, searchIndexState, stemmerCache, stemsState, vectorIndexCounts, } from "../../store/store.js";
+import { drainNoteIndex, dropAllUnusedVectors, fillSearchIndex, fillStems, involvementStoreOver, noteIndexState, openSqlite, openStore, orphanPointers, pendingNormalization, resetAttachmentWords, resetNoteIndex, resetSearchIndex, resetStems, rollBack, searchIndexState, stemmerCache, stemsState, vectorIndexCounts, } from "../../store/store.js";
 import { environmentOf, outputFor } from "../context.js";
 import { destroysNothing, LOCAL_READ, LOCAL_WRITE } from "../effects.js";
 import { itemOf, renderAnswer, snakeKeys } from "../envelope.js";
@@ -362,7 +362,11 @@ const migrateCommand = (messenger) => annotate(new Command("migrate"), { output:
     }
     const answer = await reading(path, (database) => {
         const from = schemaOf(database).version;
-        migrate(database, { command: messenger.app.command, version: messenger.app.version });
+        migrate(database, {
+            command: messenger.app.command,
+            version: messenger.app.version,
+            rollback: { store: path, warn: (line) => renderer.warn(line) },
+        });
         const { normalized, indexed, terms } = buildWordIndex(database, (note) => renderer.note(note));
         const stemmed = buildStems(database, (note) => renderer.note(note));
         const notes = buildNoteIndex(database, (note) => renderer.note(note));
@@ -533,9 +537,11 @@ const decryptCommand = () => annotate(new Command("decrypt"), { output: { entity
  * `serve` runs: that opens the store on its first write, so until then it holds nothing to see.
  */
 const restoreCommand = (messenger) => annotate(new Command("restore"), { output: { entity: "store_restore" }, effects: LOCAL_WRITE })
-    .summary("restore a backup while keeping the current store")
-    .description("put a backup in place of the store; the store it replaces is kept beside it, never deleted")
-    .argument("<file>", "a file `store backup` wrote; one written with --encrypt asks for its password")
+    .summary("restore a backup and keep the current store, or roll back a breaking upgrade")
+    .description("put a backup in place of the store; the store it replaces is kept beside it, never deleted. Given a rollback " +
+    "copy (backups/<store>-rollback-schema-<version>-<time>.db, kept for a day before an upgrade older tools " +
+    "cannot open), put its tables back in the store and return it to that version instead")
+    .argument("<file>", "a file `store backup` wrote, or a rollback copy; one written with --encrypt asks for its password")
     .action(async function (file) {
     const path = storePath(environmentOf(this).env ?? process.env);
     const given = resolve(file);
@@ -560,6 +566,8 @@ const restoreFrom = async (command, messenger, backup, given) => {
     if (existsSync(path) && realpathSync(backup) === realpathSync(path)) {
         throw new CliError("validation_error", `${backup} is the store itself`);
     }
+    if (await isRollbackCopy(backup))
+        return rollBackFrom(command, messenger, backup);
     const schema = await backupSchema(backup);
     const stamp = stampNow();
     const kept = existsSync(path) ? `${path}.before-restore-${stamp}` : null;
@@ -588,6 +596,47 @@ const restoreFrom = async (command, messenger, backup, given) => {
         renderer.note(`the backup is behind this build; the next command migrates it — \`${lineOf(command, "store migrate")}\` now`);
     }
 };
+const isRollbackCopy = async (file) => {
+    try {
+        return await readingOnly(file, (database) => database.prepare("SELECT 1 FROM sqlite_master WHERE name = 'rollback_meta'").get() !== undefined);
+    }
+    catch {
+        return false;
+    }
+};
+/** In place, in one transaction: the copy holds only the tables the upgrade changed, never a whole store. */
+const rollBackFrom = async (command, messenger, copy) => {
+    const { renderer } = outputFor(command);
+    const path = storePath(environmentOf(command).env ?? process.env);
+    if (!existsSync(path))
+        throw new CliError("not_found", `no store at ${path} to roll back`);
+    const waitMs = environmentOf(command).storeLockWaitMs;
+    await quiesce(path, messenger, "restore", (message) => renderer.warn(message), waitMs);
+    const { database } = await openSqlite(path);
+    let rolled;
+    try {
+        rolled = rollBack(database, copy);
+    }
+    finally {
+        database.close();
+    }
+    result(command, {
+        path,
+        restoredFrom: copy,
+        rolledBack: true,
+        schema: rolled.from,
+        was: rolled.was,
+        tables: rolled.restored,
+        rebuilt: rolled.rebuilt,
+        foreignKeyViolations: rolled.foreignKeyViolations,
+    });
+    const taken = new Date(rolled.createdAt).toISOString();
+    renderer.note(`the store is back at schema ${rolled.from}; ${rolled.tables.length > 0 ? rolled.tables.join(", ") : "no table"} ` +
+        `hold what they held at ${taken}, and what was written to them since is not kept`);
+    renderer.note("open it with the older tool and run its `store rebuild`: the search indexes are behind the tables");
+    renderer.note(`a tool that speaks schema ${rolled.to} or later migrates it again on its next run`);
+    renderer.note("restart every serve and mcp of either CLI that was running, so they read the restored store");
+};
 const backupSchema = async (backup) => {
     let read;
     try {

package/dist/cli/schedule/schedule-command.d.ts

@@ -1,5 +1,5 @@
 import { Command } from "commander";
-import { type AgentCli, type Schedule } from "../../background/schedules.js";
+import { type AgentCli, type AgentInput, type Schedule } from "../../background/schedules.js";
 import { type MailWaiting } from "../../mail/marks.js";
 import { type AppIdentity } from "../../ports/app.js";
 import { type AnswerOutput } from "../envelope.js";
@@ -19,6 +19,8 @@ export interface ScheduleHost {
      * then runs only once enough of it waits, or the oldest has waited long enough.
      */
     newMail?: (command: Command, holder: string) => Promise<MailWaiting>;
+    /** What an agent is given on its stdin before its first turn; see `AgentInput`. */
+    agentInput?: AgentInput;
     /** The config file's settings for agent schedules; a schedule's own flags win, the defaults fill the rest. */
     limits?: (command: Command) => ScheduleLimits;
     /**
@@ -47,5 +49,5 @@ export declare const scheduleLimitsOf: (config: {
  * (macOS) or Task Scheduler (Windows). Every timer runs `schedule exec <file>`; the schedule file holds
  * the rest, so what runs and with which variables is the same on all three.
  */
-export declare const scheduleCommandFor: ({ app, context: contextOf, newMail, limits: configured, agentRuns, }: ScheduleHost) => Command;
+export declare const scheduleCommandFor: ({ app, context: contextOf, newMail, agentInput, limits: configured, agentRuns, }: ScheduleHost) => Command;
 export {};

package/dist/cli/schedule/schedule-command.js

@@ -157,7 +157,7 @@ const runCapOf = (argv) => {
  * (macOS) or Task Scheduler (Windows). Every timer runs `schedule exec <file>`; the schedule file holds
  * the rest, so what runs and with which variables is the same on all three.
  */
-export const scheduleCommandFor = ({ app, context: contextOf, newMail, limits: configured, agentRuns = [], }) => {
+export const scheduleCommandFor = ({ app, context: contextOf, newMail, agentInput, limits: configured, agentRuns = [], }) => {
     const agentClis = [app, ...agentRuns];
     const command = new Command("schedule").description(`run a ${app.command} command or an agent later or on a timer (systemd, launchd, Task Scheduler); an agent cannot send`);
     const prepare = (self, resolving = {}) => {
@@ -427,6 +427,7 @@ export const scheduleCommandFor = ({ app, context: contextOf, newMail, limits: c
         const last = await untilChildEnds(this, (signal) => runSchedule(app, system, context.env, scheduleFile(state, scheduleName(name)), {
             timer: timer(),
             agentRuns,
+            ...(agentInput ? { agentInput } : {}),
             ...(signal ? { signal } : {}),
         }));
         say(snakeKeys({ name, ...last }), [`${name}: exit ${last.exitCode} — ${last.output}`]);
@@ -462,6 +463,7 @@ export const scheduleCommandFor = ({ app, context: contextOf, newMail, limits: c
         const last = await untilChildEnds(this, (signal) => runSchedule(app, system, context.env, file, {
             timer: timer(),
             agentRuns,
+            ...(agentInput ? { agentInput } : {}),
             untilUnlocked: true,
             ...(signal ? { signal } : {}),
         }));

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

@@ -4,6 +4,8 @@ import type { AppIdentity } from "../../ports/app.js";
 import type { MessageStore } from "../../store/store.js";
 import type { AccountKey } from "../../store/types.js";
 import type { CrmSource } from "../source.js";
+import type { CrmWriteCapabilities } from "../writer.js";
+import { type CrmWrites } from "../writes.js";
 /**
  * The selected profile's CRM account, opened by the app for one command and closed once its answer is built, before
  * anything is printed (WC-LIFE-4).
@@ -18,6 +20,8 @@ export interface CrmRun {
     source: () => CrmSource;
     /** A profile lock pins the process (WC-ACCT-5): `search all` then reads only this account's deals. */
     locked?: boolean;
+    /** The CRM's writer and the profile's levels, built on first use; needed by every write command. */
+    writes?: () => CrmWrites;
     env?: NodeJS.ProcessEnv;
     close?: () => Promise<void>;
 }
@@ -30,6 +34,8 @@ export interface CrmCommandOptions {
     }) => Promise<CrmRun>;
     /** The CRM has leads: mounts `leads list|show`. True when absent. */
     leads?: boolean;
+    /** The writer's capabilities: mounts `create`, `update`, `move`, `close` and `delete` of each kind it writes. */
+    writes?: CrmWriteCapabilities;
     now?: () => number;
 }
 /** What `deals list` and `leads list` narrow by, the same in memo and every CRM CLI (WC-OUT-11). */

package/dist/crm/cli/index.js

@@ -1,18 +1,21 @@
 import { CliError } from "@wirecat/cli-base";
 import { annotate, metaOf, sharedCommand } from "@wirecat/cli-base/commands";
-import { InvalidArgumentError } from "commander";
+import { Argument, InvalidArgumentError } from "commander";
 import * as v from "valibot";
 import { answerEntity } from "../../cli/answer-entity.js";
 import { environmentOf, outputFor, runBudgetOf } from "../../cli/context.js";
 import { honoursDryRun } from "../../cli/dry-run-guard.js";
-import { FETCH, LOCAL_READ, NO_EFFECTS } from "../../cli/effects.js";
+import { FETCH, LOCAL_READ, NO_EFFECTS, REMOTE_WRITE } from "../../cli/effects.js";
 import { itemOf, listOf, renderAnswer, snakeKeys } from "../../cli/envelope.js";
 import { queryTerms, termField, withQuery } from "../../cli/list-query.js";
+import { terminalAsker } from "../../cli/messenger/ask.js";
 import { lineOf } from "../../cli/steps.js";
 import { CRM_KINDS } from "../../domain/crm.js";
 import { DEAL_KINDS, DEAL_STATUSES } from "../../domain/deals.js";
+import { deal as dealEntity } from "../../entities/deal.js";
 import { count, text } from "../../entities/fields.js";
 import { crmStatus, syncCrm } from "../sync.js";
+import { closeCrmItem, createCrmItem, moveCrmItem, removeCrmItem, updateCrmItem, } from "../writes.js";
 import { addCrmSearchAll } from "./search-all.js";
 const MOST = 500;
 const DEAL_FIELDS = [
@@ -83,6 +86,24 @@ const crmSyncProgress = v.strictObject({
     cursor_age_ms: v.nullable(count),
     line: text,
 });
+const crmWrite = v.strictObject({
+    operation_id: text,
+    deal: v.optional(dealEntity),
+    lead: v.optional(dealEntity),
+    untrusted: v.array(text),
+});
+const crmRemoval = v.strictObject({ operation_id: text, ref: text, removed: count });
+const collect = (value, previous = []) => {
+    if (value.indexOf("=") < 1)
+        throw new InvalidArgumentError("expected code=value");
+    return [...previous, value];
+};
+/** `--field code=value` pairs; an empty value clears the field. */
+const customOf = (pairs) => Object.fromEntries(pairs.map((pair) => {
+    const at = pair.indexOf("=");
+    const given = pair.slice(at + 1);
+    return [pair.slice(0, at), given === "" ? null : given];
+}));
 const integer = (most) => (value) => {
     if (!/^[1-9]\d*$/.test(value) || Number(value) > most)
         throw new InvalidArgumentError(`expected 1 to ${most}`);
@@ -219,6 +240,7 @@ const addCrmCommandsDefinition = (program, options) => {
                 return itemOf({ ...snakeKeys(found), untrusted: DEAL_UNTRUSTED });
             });
         });
+        addWrites(group, kind);
     };
     /** A row of this profile's account: another account's copy, or the owner's own, is not found here. */
     const ownCopy = async (run, kind, reference) => {
@@ -231,6 +253,100 @@ const addCrmCommandsDefinition = (program, options) => {
             throw new CliError("not_found", `${reference} is not a copy from this profile's CRM account`);
         return found;
     };
+    const writes = options.writes;
+    const addWrites = (group, kind) => {
+        if (!writes?.kinds.includes(kind))
+            return;
+        const plural = `${kind}s`;
+        const contextOf = (run, command) => {
+            if (!run.writes)
+                throw new CliError("configuration_error", "this profile cannot write to its CRM");
+            return {
+                store: run.store,
+                account: run.account,
+                writes: run.writes(),
+                ask: terminalAsker(command),
+                source: run.source,
+                names: { id: "--operation-id" },
+            };
+        };
+        const answered = (operationId, item) => itemOf({
+            operation_id: operationId,
+            [kind]: { ...snakeKeys(item), untrusted: DEAL_UNTRUSTED },
+            untrusted: DEAL_UNTRUSTED.map((field) => `${kind}.${field}`),
+        });
+        const write = (name, verb, description) => {
+            if (!writes.verbs.includes(verb))
+                return undefined;
+            const command = answerEntity(annotate(group.command(name), { effects: REMOTE_WRITE, offline: false }), verb === "remove" ? "crm_removal" : "crm_write", verb === "remove" ? crmRemoval : crmWrite).description(description);
+            if (writes.idempotent)
+                command.option("--operation-id <id>", "the operation_id a write that ended in outcome_unknown named: the CRM answers the repeat from its record");
+            return command;
+        };
+        const reference = (command) => command.argument("<ref>", `${kind}:<id>, as a list shows it`);
+        const fields = (command) => command
+            .option("--title <title>", `the ${kind}'s title`)
+            .option("--pipeline <pipeline>", "pipeline:<id>, or a name only one of the CRM's pipelines has")
+            .option("--stage <stage>", "a stage of its pipeline, by the CRM's id or name; checks the move key too, and the close key for a won or lost stage")
+            .option("--amount <decimal>", "the expected sum, such as 1500.50, with --currency")
+            .option("--currency <code>", "an ISO 4217 code, such as EUR")
+            .option("--close-date <date>", "the day it is expected to close, YYYY-MM-DD")
+            .option("--owner <user>", "the CRM user it is assigned to; anyone but the sign-in's own user checks crm.assign-others")
+            .option("--field <key=value>", "one of the CRM's own fields, by its code; repeat for more, empty clears it", collect, 
+        // The empty default marks the flag as repeatable, so an agent's tool takes a list.
+        []);
+        const inputOf = ({ field, operationId: _id, ...rest }) => ({
+            ...Object.fromEntries(Object.entries(rest).filter(([, value]) => value !== undefined)),
+            ...(field?.length ? { custom: customOf(field) } : {}),
+        });
+        const idOf = (opts) => opts.operationId === undefined ? {} : { operationId: opts.operationId };
+        const run = (command, work) => within(command, (opened) => work(contextOf(opened, command)));
+        const create = write("create", "create", `make a ${kind} in the CRM, then store the CRM's copy of it`);
+        if (create)
+            example(fields(create), `${plural} create --title "Example kitchen" --amount 15000 --currency EUR`, `${plural} create --title "Example office" --pipeline Sales --stage "Quote sent" --field UF_CRM_SOURCE=web`).action(async (opts, command) => {
+                await run(command, async (context) => {
+                    const done = await createCrmItem(context, kind, inputOf(opts), idOf(opts));
+                    return answered(done.operationId, done.item);
+                });
+            });
+        const update = write("update", "update", `change a ${kind} in the CRM; what is left out keeps its value; the CRM's copy is stored again`);
+        if (update)
+            example(fields(reference(update)), `${plural} update ${kind}:12 --amount 18000`, `${plural} update ${kind}:12 --field UF_CRM_SOURCE=`).action(async (ref, opts, command) => {
+                await run(command, async (context) => {
+                    const done = await updateCrmItem(context, kind, ref, inputOf(opts), idOf(opts));
+                    return answered(done.operationId, done.item);
+                });
+            });
+        const move = write("move", "move", `move a ${kind} to another stage of its pipeline; a won or lost stage checks the close key too`);
+        if (move)
+            example(reference(move).argument("<stage>", "the stage, by the CRM's id or a name only one stage of its pipeline has"), `${plural} move ${kind}:12 "Quote sent"`).action(async (ref, stage, opts, command) => {
+                await run(command, async (context) => {
+                    const done = await moveCrmItem(context, kind, ref, stage, idOf(opts));
+                    return answered(done.operationId, done.item);
+                });
+            });
+        const close = write("close", "close", `mark a ${kind} won or lost, the CRM's own way`);
+        if (close)
+            example(reference(close)
+                .addArgument(new Argument("<outcome>", "how it ended").choices(["won", "lost"]))
+                .option("--reason <text>", "why, in a few words; kept with it"), `${plural} close ${kind}:12 won`, `${plural} close ${kind}:12 lost --reason "Example: chose another supplier"`).action(async (ref, outcome, opts, command) => {
+                await run(command, async (context) => {
+                    const done = await closeCrmItem(context, kind, ref, outcome, {
+                        ...idOf(opts),
+                        ...(opts.reason === undefined ? {} : { reason: opts.reason }),
+                    });
+                    return answered(done.operationId, done.item);
+                });
+            });
+        const remove = write("delete", "remove", `delete a ${kind} in the CRM; asks first unless allowed`);
+        if (remove)
+            example(reference(remove), `${plural} delete ${kind}:12`).action(async (ref, opts, command) => {
+                await run(command, async (context) => {
+                    const done = await removeCrmItem(context, kind, ref, idOf(opts));
+                    return itemOf({ operation_id: done.operationId, ref: done.ref, removed: done.removed });
+                });
+            });
+    };
     items("deal");
     if (options.leads !== false)
         items("lead");

package/dist/crm/index.d.ts

@@ -1,2 +1,4 @@
 export type { CrmChanges, CrmIdPage, CrmPage, CrmSource, CrmSourceTraits } from "./source.js";
 export { type CrmCursor, type CrmSyncIssue, type CrmSyncOptions, type CrmSyncReport, type CrmSyncResult, crmStatus, cursorName, parseCrmCursor, syncCrm, } from "./sync.js";
+export { CRM_ASSIGN_OTHERS_KEY, CRM_VERBS, CRM_WRITE_DEFAULTS, CRM_WRITE_KEYS, type CrmDraft, type CrmFields, type CrmVerb, type CrmWriteCapabilities, type CrmWriteOptions, type CrmWriter, } from "./writer.js";
+export { type CrmFieldsInput, type CrmWriteContext, type CrmWrites, type CrmWritten, closeCrmItem, createCrmItem, moveCrmItem, removeCrmItem, updateCrmItem, } from "./writes.js";

package/dist/crm/index.js

@@ -1 +1,3 @@
 export { crmStatus, cursorName, parseCrmCursor, syncCrm, } from "./sync.js";
+export { CRM_ASSIGN_OTHERS_KEY, CRM_VERBS, CRM_WRITE_DEFAULTS, CRM_WRITE_KEYS, } from "./writer.js";
+export { closeCrmItem, createCrmItem, moveCrmItem, removeCrmItem, updateCrmItem, } from "./writes.js";

package/dist/crm/testing/index.d.ts

@@ -1,3 +1,4 @@
-export { exampleDeal, exampleLead, exampleOrganization, examplePerson, type FakeCrmSource, type FakeCrmSourceOptions, fakeCrmSource, LEAD_PIPELINE, SALES_PIPELINE, } from "./source.js";
+export { exampleDeal, exampleLead, exampleOrganization, examplePerson, FAKE_CRM_ALIASES, type FakeCrmSource, type FakeCrmSourceOptions, type FakeCrmWrite, fakeCrmSource, LEAD_PIPELINE, SALES_PIPELINE, } from "./source.js";
 export { type CrmSourceFixture, crmSourceContract } from "./source-contract.js";
 export { CRM_TRAIT_COMBINATIONS, type CrmSyncFixture, crmSyncContract } from "./sync-contract.js";
+export { type CrmWriteFixture, crmWriteContract } from "./write-contract.js";

package/dist/crm/testing/index.js

@@ -1,3 +1,4 @@
-export { exampleDeal, exampleLead, exampleOrganization, examplePerson, fakeCrmSource, LEAD_PIPELINE, SALES_PIPELINE, } from "./source.js";
+export { exampleDeal, exampleLead, exampleOrganization, examplePerson, FAKE_CRM_ALIASES, fakeCrmSource, LEAD_PIPELINE, SALES_PIPELINE, } from "./source.js";
 export { crmSourceContract } from "./source-contract.js";
 export { CRM_TRAIT_COMBINATIONS, crmSyncContract } from "./sync-contract.js";
+export { crmWriteContract } from "./write-contract.js";

package/dist/crm/testing/source-contract.js

@@ -29,11 +29,11 @@ const listAll = async (source, kind, cursor) => {
 export const crmSourceContract = (make) => {
     const cases = [
         {
-            name: "pipelines: unique ids across both kinds, stages with a known outcome and unique ids",
+            name: "pipelines: unique ids in each kind, stages with a known outcome and unique ids",
             async run() {
                 const { source } = await make();
-                const seen = new Set();
                 for (const kind of DEAL_KINDS.filter((one) => source.traits.kinds.includes(one))) {
+                    const seen = new Set();
                     const pipelines = await source.pipelines(kind);
                     assert.ok(pipelines.length > 0, `${kind}: at least one pipeline`);
                     for (const pipeline of pipelines) {

package/dist/crm/testing/source.d.ts

@@ -1,13 +1,27 @@
 import type { CrmItem, CrmKind, CrmOrganization, CrmPerson, CrmPipeline, CrmRecords } from "../../domain/crm.js";
 import type { DealKind } from "../../domain/deals.js";
 import type { CrmSource, CrmSourceTraits } from "../source.js";
+import { type CrmVerb, type CrmWriteCapabilities, type CrmWriter } from "../writer.js";
 export interface FakeCrmSourceOptions {
     traits?: Partial<CrmSourceTraits>;
     /** Rows per page of `changes()` and `ids()`; 2 when absent, so every list has several pages. */
     pageSize?: number;
+    /** What the write side takes: every verb on both kinds, not idempotent, when absent. */
+    capabilities?: Partial<CrmWriteCapabilities>;
 }
-/** A CRM held in memory, with a change feed: what the contracts sync against, and what a CLI's tests may use. */
-export interface FakeCrmSource extends CrmSource {
+/** One write the fake CRM was sent, in order. */
+export interface FakeCrmWrite {
+    verb: CrmVerb;
+    kind: DealKind;
+    externalId: string | null;
+    operationId: string;
+}
+/**
+ * A CRM held in memory, with a change feed and a write side: what the contracts sync and write against, and what a
+ * CLI's tests may use. Custom field codes `stage`, `pipeline`, `owner` and `status` are refused, as an adapter refuses
+ * a custom code that names one of the neutral fields.
+ */
+export interface FakeCrmSource extends CrmSource, CrmWriter {
     /** Adds or changes a row; it is in the next `changes()`. */
     put<K extends CrmKind>(kind: K, record: CrmRecords[K]): void;
     /** Deletes a row: named in `removed` when `removedInChanges`, otherwise only missing from `ids()`. */
@@ -17,13 +31,19 @@ export interface FakeCrmSource extends CrmSource {
     expireCursors(kind: CrmKind): void;
     /** Lists no id at all, as a CRM does for a sign-in that lost its rights. */
     hideAll(hidden: boolean): void;
+    /** The next write is carried out and its answer lost: it throws `outcome_unknown`. */
+    loseNextAnswer(): void;
     /** Requests made, by method. */
     readonly calls: {
         pipelines: number;
         changes: number;
         ids: number;
     };
+    /** Writes sent, refused ones included. */
+    readonly writes: FakeCrmWrite[];
 }
+/** Custom codes the fake refuses: each is a neutral field under another name. */
+export declare const FAKE_CRM_ALIASES: string[];
 export declare const SALES_PIPELINE: CrmPipeline;
 export declare const LEAD_PIPELINE: CrmPipeline;
 export declare const fakeCrmSource: (options?: FakeCrmSourceOptions) => FakeCrmSource;