@mulmoclaude/core 0.23.0 → 0.23.1

package/assets/helps/collection-skills.md

@@ -854,6 +854,13 @@ records through **`manageCollection`**, not raw file I/O:
   / `fields` on large collections to keep the result small — e.g.
   `fields: ["id"]` to check for an id collision before an add.
 - **Delete** — remove the record file (`manageCollection` has no delete).
+- **Aggregate — `queryItems`.** Counts, sums, averages, group-bys on ANY
+  collection via a structured query (`groupBy` / `aggregates` / `where` /
+  `orderBy` / `limit` — full shape in the "External data (CSV) collections"
+  section below). On file-backed collections it aggregates the ENRICHED
+  records, so computed fields (`derived` / `rollup` / `toggle`) are
+  queryable columns — "sum of invoice totals" works even when `total` is a
+  formula. Prefer it over doing arithmetic on `getItems` output.
 - **Cross-collection questions — `getOntology`.** Returns every collection in
   the workspace with its `primaryKey`, effective `displayField`, record count,
   and its `ref` / `embed` / `backlinks` / `rollup` relations (field → related slug, including refs
@@ -961,10 +968,11 @@ Semantics to remember (and to tell the user):
   logged). Fine for browsing — but NEVER compute an aggregate from
   `getItems` output on a large file (a capped scan gives a silently wrong
   number). Use `queryItems` instead.
-- **Aggregation — `manageCollection` `queryItems`** (dataSource collections
-  only): a structured query over the WHOLE file (uncapped scan, DuckDB
-  underneath). Answer counts / sums / averages / group-bys with it —
-  don't shell out to python/pandas for questions it covers. Shape:
+- **Aggregation — `manageCollection` `queryItems`**: a structured query over
+  the WHOLE file (uncapped scan, DuckDB underneath). Answer counts / sums /
+  averages / group-bys with it — don't shell out to python/pandas for
+  questions it covers. (It works on EVERY collection — see the Records
+  section; this bullet is about the dataSource specifics.) Shape:
 
   ```json
   {

package/assets/helps/custom-view.md

@@ -101,12 +101,14 @@ toggles, embeds) — the same numbers the user sees elsewhere.
   / shows one record at a time. Combinable with `fields`.
 - The primary key is always returned regardless of `fields`.
 
-### Aggregation queries (dataSource/CSV collections; `read` capability)
+### Aggregation queries (`read` capability)
 
-On a collection backed by an external CSV (`dataSource` in its schema), a
-view can run structured aggregations over the WHOLE file — the honest way
-to chart big data (the record read above is row-capped at 5,000; an
-aggregate computed from it would be silently wrong):
+A view can run structured aggregations over the collection — on a
+`dataSource` (CSV) collection this scans the WHOLE file (the record read
+above is row-capped at 5,000 there, so an aggregate computed from it would
+be silently wrong); on a file-backed collection it aggregates the ENRICHED
+records, so computed fields (`derived` / `rollup` / `toggle`) are queryable
+columns:
 
 ```js
 const res = await fetch(dataUrl + "/query", {
@@ -130,10 +132,12 @@ const { rows } = await res.json(); // [{ Category, total, n }, ...] — chart th
   `groupBy`/`aggregates`; `orderBy` sorts by a groupBy column or an
   aggregate alias; result rows clamp at 1,000 by default.
 - Structured JSON only — there is **no SQL surface**, by design.
-- A file-backed (non-dataSource) collection answers 400 ("file-backed") —
-  compute from the record read instead there.
-- Combine with `onChange` (below) to re-run the query when the CSV is
-  replaced — that's a live dashboard.
+- Combine with `onChange` (below) to stay live: in the callback, re-run
+  **this POST query** (wrap it in your own `refresh()` and register that)
+  — NOT the `?fields=` record read from the section above, which would
+  silently repaint an aggregation view with non-aggregated data. A
+  replaced CSV or edited records then redraw the chart — that's a live
+  dashboard.
 
 ### Writing records (only with the `write` capability)
 

package/assets/skills-preset/mc-zenn/SKILL.md

@@ -43,9 +43,11 @@ unless the user already told you:
 
 - **Clone an existing Zenn repo** (they already write Zenn on GitHub). Get the
   repo URL, then:
+
   ```bash
   git clone <url> github/zenn
   ```
+
   `npx zenn` fetches zenn-cli on demand, so a missing local dependency is fine.
 
 - **Create a fresh project** (standard zenn-cli flow):
@@ -90,6 +92,7 @@ fill it in. **A published slug becomes the article URL and can't change** — pi
 it deliberately.
 
 **Step 3 — write the frontmatter** (Zenn house style):
+
 ```yaml
 ---
 title: "<a clear title, in the user's language>"
@@ -99,6 +102,7 @@ topics: ["MulmoClaude", "<related>"]
 published: true
 ---
 ```
+
 - **Always include `MulmoClaude` in `topics`.** At most 5 topics, no spaces
   inside a single topic.
 - `type` defaults to `tech`; `published` defaults to `true` (use `false` when
@@ -109,6 +113,33 @@ implementation (fenced ` ```lang ` blocks, runnable commands) → result → a s
 wrap-up. Informative but casual; describe the work, not yourself. Put images in
 `github/zenn/images/` and reference them as `![alt](/images/<file>)`.
 
+Write it the way a person would, not the way a model defaults to. Each rule
+below comes from real reader feedback — ignore them and the draft reads as
+machine output:
+
+- **Sound human, not like a generated listicle.** Prefer flowing prose over
+  walls of bullets, use bold sparingly, and let paragraphs connect into an
+  argument. If every section is just a heading plus a list, vary the rhythm.
+- **No uncommon loanwords or jargon.** Use only terms a typical reader already
+  knows. Niche English acronyms, trendy katakana, and insider slang either get
+  dropped or replaced with plain words. A term the field itself hasn't settled
+  on ("code smell" and the like) is a red flag — say the plain thing instead
+  ("code that works now but bites you later").
+- **Define every term and acronym on first use**, in plain language, and put the
+  foundational ones up front — define "DRY" before the article leans on it. A
+  reader should never hit a word they can't parse.
+- **Carry a source's essence, don't just cite it.** When an idea comes from a
+  book or article, explain the idea itself in your own words; "see <book>"
+  teaches nothing. Search for the actual content when you're unsure what it says,
+  then write the substance.
+- **Make the article self-contained.** Anything project-specific — a repo's
+  internals, a config choice, a domain constraint — needs enough general
+  background that a reader with zero context can follow. Running longer is fine
+  when the extra length buys understanding.
+- **Match the stated audience.** "Explain to intermediate developers" means
+  patient explanations, concrete examples, real code from the work, and links —
+  not a terse summary.
+
 **Step 5 — save + preview.** Write `github/zenn/articles/<slug>.md`. Tell the
 user the path and how to preview: `cd github/zenn && npx zenn preview`
 (http://localhost:8000). Surface the title, slug, and topics.

package/dist/collection/registry/server/index.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_rolldown_runtime = require("../../../rolldown-runtime-D6vf50IK.cjs");
-const require_server = require("../../../server-Q7ld-FlZ.cjs");
+const require_server = require("../../../server-Jaogu3Ky.cjs");
 const require_collection_paths = require("../../paths.cjs");
 const require_skill_bridge_index = require("../../../skill-bridge/index.cjs");
 const require_types = require("../../../types-CNqkLT4M.cjs");

package/dist/collection/registry/server/index.js

@@ -1,4 +1,4 @@
-import { D as CollectionSchemaZ, S as acceptParsedSchema, _ as errorMessage, g as ONE_SECOND_MS, ht as collectionsRegistriesConfigPath, ot as writeFileAtomic, pt as safeRecordId, vt as log, w as loadCollection } from "../../../server--FgDORd3.js";
+import { D as CollectionSchemaZ, S as acceptParsedSchema, _ as errorMessage, _t as collectionsRegistriesConfigPath, bt as log, ct as writeFileAtomic, g as ONE_SECOND_MS, ht as safeRecordId, w as loadCollection } from "../../../server-D2ibbixF.js";
 import { isSafeActionTemplatePath } from "../../paths.js";
 import { claudeSkillDir, dataSkillDir, mirrorSkillWrite } from "../../../skill-bridge/index.js";
 import { n as parseRegistryIndex, r as isRecord, t as OFFICIAL_REGISTRY_NAME } from "../../../types-BKVZrtyc.js";

package/dist/collection/server/csvQuery.d.ts

@@ -8,12 +8,20 @@ export declare function quoteLiteral(value: string): string;
  *  DuckDB's sniffer turns `001` into BIGINT 1, so leading zeros vanish
  *  and distinct keys collapse. */
 export declare function readCsvArgs(primaryKey: string): string;
-/** Compile a validated query. Returns the SQL (whose FIRST placeholder is
- *  the CSV path — the executor binds it) and the where-value parameters
- *  that follow it. Callers MUST have run `CollectionQueryZ` first; this
- *  function trusts the shape (aliases already charset-checked, orderBy
- *  membership already enforced). */
+/** Compile against a CSV file (the dataSource store's engine). */
 export declare function compileCsvQuery(query: CollectionQuery, primaryKey: string): {
     sql: string;
     params: unknown[];
 };
+/** Compile against a JSONL file of ENRICHED records — the file-backed
+ *  collections' engine (see `jsonlQuery.ts`). No VARCHAR key pin needed:
+ *  enriched record ids are already strings. `sample_size=-1` makes the
+ *  schema inference scan EVERY line — with the default sample, a sparse
+ *  optional/derived field first appearing past the sample would not be
+ *  inferred as a column and the query would binder-error on it (Codex P2
+ *  on #2165). The full scan costs nothing extra here: aggregation reads
+ *  the whole file anyway. */
+export declare function compileJsonlQuery(query: CollectionQuery): {
+    sql: string;
+    params: unknown[];
+};

package/dist/collection/server/csvStore.d.ts

@@ -30,6 +30,8 @@ export declare function dedupeByRecordId(items: CollectionItem[], primaryKey: st
     items: CollectionItem[];
     duplicates: number;
 };
+export declare function cacheDir(): string;
+export declare function queryCsv(sql: string, params: unknown[]): Promise<Record<string, unknown>[]>;
 /** Every row of the CSV as records — capped, deduped, id-encoded. The
  *  key column is pinned to VARCHAR (see `readCsvArgs`). `workspaceRoot`
  *  drives the per-read containment check; omitted, the configured host

package/dist/collection/server/index.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_promptSafety = require("../../promptSafety-DRd15gQ6.cjs");
-const require_server = require("../../server-Q7ld-FlZ.cjs");
+const require_server = require("../../server-Jaogu3Ky.cjs");
 const require_collection_paths = require("../paths.cjs");
 exports.COMPUTED_TYPES = require_promptSafety.COMPUTED_TYPES;
 exports.CollectionQueryZ = require_server.CollectionQueryZ;
@@ -19,6 +19,7 @@ exports.buildCollectionActionSeedPrompt = require_server.buildCollectionActionSe
 exports.buildWorkspaceOntology = require_server.buildWorkspaceOntology;
 exports.collectionWritable = require_server.collectionWritable;
 exports.compileCsvQuery = require_server.compileCsvQuery;
+exports.compileJsonlQuery = require_server.compileJsonlQuery;
 exports.compileRecordZ = require_server.compileRecordZ;
 exports.computeCollectionIcon = require_server.computeCollectionIcon;
 exports.computeSuccessor = require_server.computeSuccessor;
@@ -66,6 +67,7 @@ exports.resolveCreateItemId = require_server.resolveCreateItemId;
 exports.resolveDataDir = require_server.resolveDataDir;
 exports.resolveEvery = require_server.resolveEvery;
 exports.resolveTemplatePath = require_server.resolveTemplatePath;
+exports.runQueryOverRows = require_server.runQueryOverRows;
 exports.safeRecordId = require_server.safeRecordId;
 exports.safeSlugName = require_server.safeSlugName;
 exports.schemaRelations = require_server.schemaRelations;

package/dist/collection/server/index.d.ts

@@ -5,7 +5,8 @@ export * from './templatePath';
 export * from './io';
 export * from './store';
 export { MAX_CSV_ROWS, encodeCsvRecordId, decodeCsvRecordId, normalizeCsvValue, csvRowToItem, dedupeByRecordId } from './csvStore';
-export { compileCsvQuery } from './csvQuery';
+export { compileCsvQuery, compileJsonlQuery } from './csvQuery';
+export { runQueryOverRows } from './jsonlQuery';
 export { CollectionQueryZ, MAX_QUERY_ROWS, DEFAULT_QUERY_ROWS } from '../core/queryZ';
 export type { CollectionQuery, CollectionQueryAggregate, CollectionQueryOrder, CollectionQueryWhere } from '../core/queryZ';
 export * from './validate';

package/dist/collection/server/index.js

@@ -1,4 +1,4 @@
 import { I as COMPUTED_TYPES } from "../../promptSafety-rDWA9_JS.js";
-import { $ as promptPathsFor, A as validateCollectionRecords, B as dedupeByRecordId, C as discoverCollections, D as CollectionSchemaZ, E as toSummary, F as readOnlyRefusal, G as DEFAULT_QUERY_ROWS, H as normalizeCsvValue, I as storeFor, J as buildCollectionActionSeedPrompt, K as MAX_QUERY_ROWS, L as MAX_CSV_ROWS, M as compileRecordZ, N as recordFieldProblem, O as applyMutateAction, P as collectionWritable, Q as listItems, R as csvRowToItem, S as acceptParsedSchema, T as toDetail, U as compileCsvQuery, V as encodeCsvRecordId, W as CollectionQueryZ, X as generateItemId, Y as deleteItem, Z as isRegularFile, _t as getWorkspaceRoot, a as deleteCollection, at as writeItem, b as buildWorkspaceOntology, bt as setCollectionChangePublisher, c as computeSuccessor, ct as isContainedInRoot, d as isTriggerDue, dt as resolveDataDir, et as readCustomViewHtml, f as maybeSpawnSuccessor, ft as resolveTemplatePath, gt as configureCollectionHost, h as successorId, i as deleteCustomView, it as resolveCreateItemId, j as validateRecordObject, k as firstMutateParamProblem, l as daysInMonth, lt as isContainedInWorkspace, m as resolveEvery, mt as safeSlugName, n as MAX_UNSELECTIVE_ITEMS, nt as readItem, o as deleteCollectionRefusalMessage, p as parseCivil, pt as safeRecordId, q as buildActionSeedPrompt, r as makeManageCollectionTool, rt as readSkillTemplate, s as advanceTriggerDate, st as SCHEMA_FILE, t as MAX_SCHEMA_ISSUES, tt as readCustomViewI18n, u as formatCivil, ut as itemFilePath, v as computeCollectionIcon, vt as log, w as loadCollection, x as schemaRelations, y as enrichItems, yt as publishCollectionChange, z as decodeCsvRecordId } from "../../server--FgDORd3.js";
+import { $ as isRegularFile, A as validateCollectionRecords, B as decodeCsvRecordId, C as discoverCollections, D as CollectionSchemaZ, E as toSummary, F as collectionWritable, G as compileJsonlQuery, H as encodeCsvRecordId, I as readOnlyRefusal, J as MAX_QUERY_ROWS, K as CollectionQueryZ, L as storeFor, M as compileRecordZ, N as recordFieldProblem, O as applyMutateAction, P as runQueryOverRows, Q as generateItemId, R as MAX_CSV_ROWS, S as acceptParsedSchema, St as setCollectionChangePublisher, T as toDetail, U as normalizeCsvValue, V as dedupeByRecordId, W as compileCsvQuery, X as buildCollectionActionSeedPrompt, Y as buildActionSeedPrompt, Z as deleteItem, a as deleteCollection, at as readSkillTemplate, b as buildWorkspaceOntology, bt as log, c as computeSuccessor, d as isTriggerDue, dt as isContainedInWorkspace, et as listItems, f as maybeSpawnSuccessor, ft as itemFilePath, gt as safeSlugName, h as successorId, ht as safeRecordId, i as deleteCustomView, it as readItem, j as validateRecordObject, k as firstMutateParamProblem, l as daysInMonth, lt as SCHEMA_FILE, m as resolveEvery, mt as resolveTemplatePath, n as MAX_UNSELECTIVE_ITEMS, nt as readCustomViewHtml, o as deleteCollectionRefusalMessage, ot as resolveCreateItemId, p as parseCivil, pt as resolveDataDir, q as DEFAULT_QUERY_ROWS, r as makeManageCollectionTool, rt as readCustomViewI18n, s as advanceTriggerDate, st as writeItem, t as MAX_SCHEMA_ISSUES, tt as promptPathsFor, u as formatCivil, ut as isContainedInRoot, v as computeCollectionIcon, vt as configureCollectionHost, w as loadCollection, x as schemaRelations, xt as publishCollectionChange, y as enrichItems, yt as getWorkspaceRoot, z as csvRowToItem } from "../../server-D2ibbixF.js";
 import { isSafeActionTemplatePath, isSafeCustomViewI18nPath, isSafeCustomViewPath, isSafeTemplatePath } from "../paths.js";
-export { COMPUTED_TYPES, CollectionQueryZ, CollectionSchemaZ, DEFAULT_QUERY_ROWS, MAX_CSV_ROWS, MAX_QUERY_ROWS, MAX_SCHEMA_ISSUES, MAX_UNSELECTIVE_ITEMS, SCHEMA_FILE, acceptParsedSchema, advanceTriggerDate, applyMutateAction, buildActionSeedPrompt, buildCollectionActionSeedPrompt, buildWorkspaceOntology, collectionWritable, compileCsvQuery, compileRecordZ, computeCollectionIcon, computeSuccessor, configureCollectionHost, csvRowToItem, daysInMonth, decodeCsvRecordId, dedupeByRecordId, deleteCollection, deleteCollectionRefusalMessage, deleteCustomView, deleteItem, discoverCollections, encodeCsvRecordId, enrichItems, firstMutateParamProblem, formatCivil, generateItemId, getWorkspaceRoot, isContainedInRoot, isContainedInWorkspace, isRegularFile, isSafeActionTemplatePath, isSafeCustomViewI18nPath, isSafeCustomViewPath, isSafeTemplatePath, isTriggerDue, itemFilePath, listItems, loadCollection, log, makeManageCollectionTool, maybeSpawnSuccessor, normalizeCsvValue, parseCivil, promptPathsFor, publishCollectionChange, readCustomViewHtml, readCustomViewI18n, readItem, readOnlyRefusal, readSkillTemplate, recordFieldProblem, resolveCreateItemId, resolveDataDir, resolveEvery, resolveTemplatePath, safeRecordId, safeSlugName, schemaRelations, setCollectionChangePublisher, storeFor, successorId, toDetail, toSummary, validateCollectionRecords, validateRecordObject, writeItem };
+export { COMPUTED_TYPES, CollectionQueryZ, CollectionSchemaZ, DEFAULT_QUERY_ROWS, MAX_CSV_ROWS, MAX_QUERY_ROWS, MAX_SCHEMA_ISSUES, MAX_UNSELECTIVE_ITEMS, SCHEMA_FILE, acceptParsedSchema, advanceTriggerDate, applyMutateAction, buildActionSeedPrompt, buildCollectionActionSeedPrompt, buildWorkspaceOntology, collectionWritable, compileCsvQuery, compileJsonlQuery, compileRecordZ, computeCollectionIcon, computeSuccessor, configureCollectionHost, csvRowToItem, daysInMonth, decodeCsvRecordId, dedupeByRecordId, deleteCollection, deleteCollectionRefusalMessage, deleteCustomView, deleteItem, discoverCollections, encodeCsvRecordId, enrichItems, firstMutateParamProblem, formatCivil, generateItemId, getWorkspaceRoot, isContainedInRoot, isContainedInWorkspace, isRegularFile, isSafeActionTemplatePath, isSafeCustomViewI18nPath, isSafeCustomViewPath, isSafeTemplatePath, isTriggerDue, itemFilePath, listItems, loadCollection, log, makeManageCollectionTool, maybeSpawnSuccessor, normalizeCsvValue, parseCivil, promptPathsFor, publishCollectionChange, readCustomViewHtml, readCustomViewI18n, readItem, readOnlyRefusal, readSkillTemplate, recordFieldProblem, resolveCreateItemId, resolveDataDir, resolveEvery, resolveTemplatePath, runQueryOverRows, safeRecordId, safeSlugName, schemaRelations, setCollectionChangePublisher, storeFor, successorId, toDetail, toSummary, validateCollectionRecords, validateRecordObject, writeItem };

package/dist/collection/server/jsonlQuery.d.ts

@@ -0,0 +1,4 @@
+import { CollectionItem } from '../core/schema';
+import { CollectionQuery } from '../core/queryZ';
+/** Run a validated query over enriched collection rows. */
+export declare function runQueryOverRows(rows: CollectionItem[], query: CollectionQuery): Promise<Record<string, unknown>[]>;

package/dist/collection-watchers/index.cjs

@@ -2,7 +2,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_rolldown_runtime = require("../rolldown-runtime-D6vf50IK.cjs");
 const require_promptSafety = require("../promptSafety-DRd15gQ6.cjs");
 require("../collection/index.cjs");
-const require_server = require("../server-Q7ld-FlZ.cjs");
+const require_server = require("../server-Jaogu3Ky.cjs");
 const require_notifier = require("../notifier-bS8IEeLA.cjs");
 let node_path = require("node:path");
 node_path = require_rolldown_runtime.__toESM(node_path, 1);

package/dist/collection-watchers/index.js

@@ -1,6 +1,6 @@
 import { A as whenMatches } from "../promptSafety-rDWA9_JS.js";
 import "../collection/index.js";
-import { C as discoverCollections, Q as listItems, d as isTriggerDue, f as maybeSpawnSuccessor, nt as readItem, w as loadCollection, yt as publishCollectionChange } from "../server--FgDORd3.js";
+import { C as discoverCollections, d as isTriggerDue, et as listItems, f as maybeSpawnSuccessor, it as readItem, w as loadCollection, xt as publishCollectionChange } from "../server-D2ibbixF.js";
 import { d as publish, m as updateForPlugin, n as clear, s as listAll } from "../notifier-ChpY0XrY.js";
 import path from "node:path";
 import { watch } from "node:fs";

package/dist/feeds/server/index.cjs

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_rolldown_runtime = require("../../rolldown-runtime-D6vf50IK.cjs");
 const require_promptSafety = require("../../promptSafety-DRd15gQ6.cjs");
-const require_server = require("../../server-Q7ld-FlZ.cjs");
+const require_server = require("../../server-Jaogu3Ky.cjs");
 const require_ingestTypes = require("../../ingestTypes-Cev9q77C.cjs");
 const require_feeds_paths = require("../paths.cjs");
 const require_notifier = require("../../notifier-bS8IEeLA.cjs");

package/dist/feeds/server/index.js

@@ -1,5 +1,5 @@
 import { L as FEED_SCHEDULES, R as INGEST_KINDS } from "../../promptSafety-rDWA9_JS.js";
-import { $ as promptPathsFor, C as discoverCollections, J as buildCollectionActionSeedPrompt, Q as listItems, Y as deleteItem, at as writeItem, dt as resolveDataDir, mt as safeSlugName, rt as readSkillTemplate } from "../../server--FgDORd3.js";
+import { C as discoverCollections, X as buildCollectionActionSeedPrompt, Z as deleteItem, at as readSkillTemplate, et as listItems, gt as safeSlugName, pt as resolveDataDir, st as writeItem, tt as promptPathsFor } from "../../server-D2ibbixF.js";
 import { n as DEFAULT_FEED_MAX_ITEMS, r as isFeedSchedule, t as AGENT_INGEST_KIND } from "../../ingestTypes-B-dXxUF9.js";
 import { FEEDS_DIR, feedDir, feedStatePath, feedsRoot, ingestStateDir, ingestStatePath } from "../paths.js";
 import { d as publish, n as clear } from "../../notifier-ChpY0XrY.js";

package/dist/google/auth.d.ts

@@ -1,6 +1,7 @@
 import { default as http } from 'node:http';
 import { Credentials } from 'google-auth-library';
 import { fetchWithTimeout } from './fetch.js';
+import { IssuedVia } from './tokenStore.js';
 export declare const GOOGLE_CALENDAR_SCOPE = "https://www.googleapis.com/auth/calendar.events";
 /** Minimal read scope for the calendar list + per-calendar colours.
  *  `calendar.events` already covers reading/writing events on any calendar, but
@@ -19,6 +20,9 @@ export interface AuthorizeGoogleOptions {
     /** Called with the consent URL; open it in a browser (and/or print it). */
     onAuthUrl?: (url: string) => void;
     timeoutMs?: number;
+    /** Abort a still-pending consent (a settings-UI restart, an explicit cancel).
+     *  Rejects the flow with {@link GOOGLE_AUTH_CANCELLED} and closes the loopback. */
+    signal?: AbortSignal;
 }
 export declare function getGoogleAccessToken(home?: string): Promise<string>;
 /** The revoke POST, injectable for tests. */
@@ -28,5 +32,10 @@ export type RevokeFetch = typeof fetchWithTimeout;
  *  already consider the token invalid, and keeping the file would leave the
  *  user unable to unlink. */
 export declare function unlinkGoogle(home?: string, revokeFetch?: RevokeFetch): Promise<void>;
-export declare const waitForAuthCode: (server: http.Server, expectedState: string, timeoutMs: number) => Promise<string>;
+/** Reject reason when a pending flow is torn down (a settings-UI restart or an
+ *  explicit cancel), kept distinct from a real authorization error so callers
+ *  can treat it as "user changed their mind", not "linking failed". */
+export declare const GOOGLE_AUTH_CANCELLED = "authorization cancelled";
+export declare const waitForAuthCode: (server: http.Server, expectedState: string, timeoutMs: number, signal?: AbortSignal) => Promise<string>;
+export declare const commitLinkedTokens: (tokens: Credentials, issuedVia: IssuedVia, opts: AuthorizeGoogleOptions) => Promise<Credentials>;
 export declare function authorizeGoogle(opts?: AuthorizeGoogleOptions): Promise<Credentials>;

package/dist/google/authFlow.d.ts

@@ -7,6 +7,7 @@ export interface GoogleAuthFlow {
     start: () => Promise<{
         authUrl: string;
     }>;
+    cancel: () => void;
     status: () => GoogleAuthFlowStatus;
 }
 export declare const createGoogleAuthFlow: (authorize: typeof authorizeGoogle) => GoogleAuthFlow;

package/dist/google/index.cjs

@@ -453,29 +453,50 @@ var respondHtml = (res, status, message) => {
 	res.writeHead(status, { "Content-Type": "text/html; charset=utf-8" });
 	res.end(`<html><body><h3>${message}</h3></body></html>`);
 };
-var waitForAuthCode = (server, expectedState, timeoutMs) => new Promise((resolve, reject) => {
+/** Reject reason when a pending flow is torn down (a settings-UI restart or an
+*  explicit cancel), kept distinct from a real authorization error so callers
+*  can treat it as "user changed their mind", not "linking failed". */
+var GOOGLE_AUTH_CANCELLED = "authorization cancelled";
+var handleCallbackRequest = (req, res, expectedState, settle) => {
+	const url = new URL(req.url ?? "/", "http://127.0.0.1");
+	if (url.pathname !== CALLBACK_PATH) {
+		res.writeHead(404);
+		res.end();
+		return;
+	}
+	if (url.searchParams.get("state") !== expectedState) {
+		respondHtml(res, 400, "Invalid authorization callback. You can close this tab.");
+		return;
+	}
+	try {
+		const code = authCodeFromCallback(url, expectedState);
+		respondHtml(res, 200, "Authorization complete — you can close this tab.");
+		settle.resolve(code);
+	} catch (err) {
+		respondHtml(res, 400, "Authorization failed — see the terminal for details. You can close this tab.");
+		settle.reject(err);
+	}
+};
+var waitForAuthCode = (server, expectedState, timeoutMs, signal) => new Promise((resolve, reject) => {
 	const timer = setTimeout(() => reject(/* @__PURE__ */ new Error(`authorization timed out after ${timeoutMs / ONE_SECOND_MS}s`)), timeoutMs);
-	server.on("request", (req, res) => {
-		const url = new URL(req.url ?? "/", "http://127.0.0.1");
-		if (url.pathname !== CALLBACK_PATH) {
-			res.writeHead(404);
-			res.end();
-			return;
+	const settle = {
+		resolve: (code) => {
+			clearTimeout(timer);
+			resolve(code);
+		},
+		reject: (err) => {
+			clearTimeout(timer);
+			reject(err instanceof Error ? err : new Error(String(err)));
 		}
-		if (url.searchParams.get("state") !== expectedState) {
-			respondHtml(res, 400, "Invalid authorization callback. You can close this tab.");
+	};
+	if (signal) {
+		if (signal.aborted) {
+			settle.reject(/* @__PURE__ */ new Error(GOOGLE_AUTH_CANCELLED));
 			return;
 		}
-		clearTimeout(timer);
-		try {
-			const code = authCodeFromCallback(url, expectedState);
-			respondHtml(res, 200, "Authorization complete — you can close this tab.");
-			resolve(code);
-		} catch (err) {
-			respondHtml(res, 400, "Authorization failed — see the terminal for details. You can close this tab.");
-			reject(err);
-		}
-	});
+		signal.addEventListener("abort", () => settle.reject(/* @__PURE__ */ new Error(GOOGLE_AUTH_CANCELLED)), { once: true });
+	}
+	server.on("request", (req, res) => handleCallbackRequest(req, res, expectedState, settle));
 });
 var buildConsentUrl = (client, codeChallenge, state) => client.generateAuthUrl({
 	access_type: "offline",
@@ -499,7 +520,7 @@ var authorizeWithLocalClient = async (secret, server, port, opts) => {
 	if (!codeChallenge) throw new Error("failed to derive a PKCE code challenge");
 	const state = (0, node_crypto.randomBytes)(STATE_BYTES).toString("hex");
 	opts.onAuthUrl?.(buildConsentUrl(client, codeChallenge, state));
-	const code = await waitForAuthCode(server, state, opts.timeoutMs ?? AUTH_TIMEOUT_MS);
+	const code = await waitForAuthCode(server, state, opts.timeoutMs ?? AUTH_TIMEOUT_MS, opts.signal);
 	const { tokens } = await client.getToken({
 		code,
 		codeVerifier
@@ -512,11 +533,18 @@ var authorizeWithBroker = async (server, port, opts) => {
 	const { authUrl, state } = await brokerStart(port, codeChallenge);
 	opts.onAuthUrl?.(authUrl);
 	return await brokerExchange({
-		code: await waitForAuthCode(server, state, opts.timeoutMs ?? AUTH_TIMEOUT_MS),
+		code: await waitForAuthCode(server, state, opts.timeoutMs ?? AUTH_TIMEOUT_MS, opts.signal),
 		state,
 		codeVerifier
 	});
 };
+var commitLinkedTokens = async (tokens, issuedVia, opts) => {
+	if (opts.signal?.aborted) throw new Error(GOOGLE_AUTH_CANCELLED);
+	return await saveGoogleTokens({
+		...tokens,
+		issuedVia
+	}, opts.home);
+};
 async function authorizeGoogle(opts = {}) {
 	const presence = await clientSecretPresence(opts.home);
 	if (presence === "ambiguous") await loadClientSecret(opts.home);
@@ -524,10 +552,7 @@ async function authorizeGoogle(opts = {}) {
 	const { server, port } = await startLoopbackServer();
 	try {
 		const issuedVia = useLocalClient ? "local" : "broker";
-		return await saveGoogleTokens({
-			...useLocalClient ? await authorizeWithLocalClient(await loadClientSecret(opts.home), server, port, opts) : await authorizeWithBroker(server, port, opts),
-			issuedVia
-		}, opts.home);
+		return await commitLinkedTokens(useLocalClient ? await authorizeWithLocalClient(await loadClientSecret(opts.home), server, port, opts) : await authorizeWithBroker(server, port, opts), issuedVia, opts);
 	} finally {
 		server.close();
 	}
@@ -535,25 +560,38 @@ async function authorizeGoogle(opts = {}) {
 //#endregion
 //#region src/google/authFlow.ts
 var createGoogleAuthFlow = (authorize) => {
-	let inFlightStart = null;
 	let flowRunning = false;
 	let lastError = null;
-	const launchFlow = () => new Promise((resolve, reject) => {
+	let active = null;
+	const launch = () => {
+		const controller = new AbortController();
+		active = controller;
 		flowRunning = true;
-		authorize({ onAuthUrl: (url) => resolve({ authUrl: url }) }).then(() => log.info("google", "authorize flow completed")).catch((err) => {
-			lastError = errorMessage(err);
-			log.warn("google", "authorize flow failed", { error: lastError });
-			reject(err instanceof Error ? err : new Error(String(err)));
-		}).finally(() => {
-			flowRunning = false;
-			inFlightStart = null;
+		return new Promise((resolve, reject) => {
+			authorize({
+				onAuthUrl: (url) => resolve({ authUrl: url }),
+				signal: controller.signal
+			}).then(() => log.info("google", "authorize flow completed")).catch((err) => {
+				if (!controller.signal.aborted) {
+					lastError = errorMessage(err);
+					log.warn("google", "authorize flow failed", { error: lastError });
+				}
+				reject(err instanceof Error ? err : new Error(String(err)));
+			}).finally(() => {
+				if (active === controller) {
+					flowRunning = false;
+					active = null;
+				}
+			});
 		});
-	});
+	};
+	const cancel = () => {
+		active?.abort();
+	};
 	const start = () => {
-		if (inFlightStart) return inFlightStart;
+		cancel();
 		lastError = null;
-		inFlightStart = launchFlow();
-		return inFlightStart;
+		return launch();
 	};
 	const status = () => ({
 		pending: flowRunning,
@@ -561,6 +599,7 @@ var createGoogleAuthFlow = (authorize) => {
 	});
 	return {
 		start,
+		cancel,
 		status
 	};
 };
@@ -863,6 +902,7 @@ async function deleteDriveFile(accessToken, input) {
 }
 //#endregion
 exports.DEFAULT_LIST_MAX_RESULTS = DEFAULT_LIST_MAX_RESULTS;
+exports.GOOGLE_AUTH_CANCELLED = GOOGLE_AUTH_CANCELLED;
 exports.GOOGLE_CALENDARLIST_SCOPE = GOOGLE_CALENDARLIST_SCOPE;
 exports.GOOGLE_CALENDAR_SCOPE = GOOGLE_CALENDAR_SCOPE;
 exports.GOOGLE_DRIVE_FILE_SCOPE = GOOGLE_DRIVE_FILE_SCOPE;
@@ -879,6 +919,7 @@ exports.buildMultipartBody = buildMultipartBody;
 exports.calendarApiError = calendarApiError;
 exports.clientSecretPresence = clientSecretPresence;
 exports.collectCalendarPages = collectCalendarPages;
+exports.commitLinkedTokens = commitLinkedTokens;
 exports.completeTask = completeTask;
 exports.configureGoogleHost = configureGoogleHost;
 exports.createCalendarEvent = createCalendarEvent;