@supersuit/suggest-a-change 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.1.4 (2026-10-14)
+
+- **The owner may decline a report Freeda has not planned.** `FLOW["with-freeda"].next` and `FLOW["planned"].next` now include `"not-now"`, so a report the reading worker cannot plan has an exit instead of showing "With Freeda" for ever. `agentStatus` accepts both moves (they take the approval, as any end does). A copy of the contract vendored elsewhere must be taken again: these are new bytes.
+- **A claim on a closed report answers 409 and never lapses.** `claim-approval` on a report at an end status answers 409 `{ closed: true, status, claimedBy }` to everyone and writes nothing; before, the seven-day approval lapsed and an eight-day-old card could take a shipped or declined report. A report being made stays with the Mac that started it: the move to `being-made` or an end now names the maintainer on its timeline entry (`holder`, not in the member's view) and takes the approval for `HELD_MS` (exported), and another Mac is answered 409 with that holder however long after. Before the work starts the approval still lapses after a week.
+- **The list never offers a report another maintainer closed.** `agentList` settles such a report for the asking maintainer without showing it, so it neither raises a notice on a second Mac nor fills the head of every page; it asks the store again when that freed slots. A report another maintainer is making carries `heldBy`. A report closed before 0.1.4 names no holder and is treated as closed by someone else.
+
 ## 0.1.3 (2026-10-13)
 
 - **The phone's saved answers belong to whoever asked.** A list or report that the app answers after the signed-in account has changed is neither saved under the earlier account's key nor drawn: the account is asked again after the answer, as the outbox does before a write.

package/README.md

@@ -12,7 +12,7 @@ npm install @supersuit/suggest-a-change
 import { KINDS, STATUSES, FLOW, CEILINGS } from "@supersuit/suggest-a-change";
 
 console.log(KINDS);            // ["change", "broken", "feedback"]
-console.log(FLOW["with-freeda"]); // { actor: "mac", next: ["planned"] }
+console.log(FLOW["with-freeda"]); // { actor: "mac", next: ["planned", "not-now"] }
 ```
 
 The package root is the report contract: the kinds, roles, ceilings, the status list and the flow map (who performs each step and which moves are allowed), plus the functions that validate a report against them. It has no imports, so it can also be copied whole into a place that has no install step. If you copy it, keep a hash of the copy and fail a test when the bytes change; fix the contract here and copy it again.
@@ -173,10 +173,10 @@ const h = createReportHandlers({
 | `GET /api/reports/mine` | `mine` | 200, 401 |
 | `GET /api/reports/:id` | `one(req, id)` | 200, 401, 404 (missing and not yours look the same) |
 | `POST /api/reports/:id/append` | `append(req, id)` | 200, 400, 401, 404 (not the owner's: same as missing), 409 (the suggestion has ended) |
-| `GET /api/agent/reports` | `agentList` | 200 `{ reports }`: one page (20, oldest first) of what is open for this Mac, each claimed for ten minutes; a report whose files are still arriving waits up to an hour |
+| `GET /api/agent/reports` | `agentList` | 200 `{ reports }`: one page (20, oldest first) of what is open for this Mac, each claimed for ten minutes; a report whose files are still arriving waits up to an hour; a report another maintainer closed is never offered (it is settled for this Mac unseen); `heldBy` names the maintainer whose Mac is making a report |
 | `GET /api/agent/reports/:id/files/:file` | `agentFile(req, id, file)` | 200 `{ url, expiresAt, type, bytes, sha256 }` (the link lives five minutes), 404 |
 | `POST /api/agent/reports/:id/settle` | `agentSettle` | body `{ revision }` (the one the list gave this report): 200, 400 (no revision), 409 (not claimed, or `stale`: something was added since the list, so the report is offered again) |
-| `POST /api/agent/reports/:id/claim-approval` | `agentClaimApproval` | 200, or 409 `{ claimedBy }` |
+| `POST /api/agent/reports/:id/claim-approval` | `agentClaimApproval` | 200, or 409 `{ claimedBy }`, or on a closed report 409 `{ closed: true, status, claimedBy? }` |
 | `POST /api/agent/reports/:id/status` | `agentStatus` | 200, 400, 409 |
 
 A client adapter's `uploadPart` asks `upload-url`, PUTs the bytes straight to storage, then calls `finalize`. Nothing is uploaded through the app's server and no handler reads a body over about 400 KB (sized from the field limits at four bytes a character; far under 4 MB).
@@ -187,7 +187,7 @@ The role stored on a report comes from the signed-in member and the `maintainers
 
 **The collector MUST verify.** `agentFile` answers the verified `bytes` and `sha256`; a Mac that downloads the link must check both before it trusts the file.
 
-**The approval.** Moves before the owner is asked (`with-freeda`, `planned`, `waiting-on-owner`) need no claim. Leaving `waiting-on-owner`, starting `being-made` and any end status need the Mac that holds the approval (taken atomically if nobody holds it, otherwise 409 with who does). The holder can release it, and it lapses after seven days.
+**The approval.** Moves before the owner is asked (`with-freeda`, `planned`, `waiting-on-owner`) need no claim. Leaving `waiting-on-owner`, starting `being-made` and any end status need the Mac that holds the approval (taken atomically if nobody holds it, otherwise 409 with who does). Before the work starts the holder can release it, and an unrenewed approval lapses after seven days. Once the work starts or ends it does not lapse: the move to `being-made` or to an end names the maintainer on its timeline entry (`holder`, never shown to the member), the approval is taken for `HELD_MS`, and another Mac asking is answered 409 with that holder. A claim on a closed report is 409 `{ closed: true, status, claimedBy }` for everyone, the holder included, and writes nothing. The owner may decline (`not-now`) from `with-freeda` and `planned` as well as from `waiting-on-owner`.
 
 **What a storage adapter implements** (`HostedStore`). Every method that changes a report is narrow and atomic: `put` is create-only (`created`, `exists`, or `limit` when the member's day is full, counted in the same transaction), and `setFile` (never replaces a verified entry; an older pending never replaces a newer one), `addFollowUp` (the caps, a reused file name and an ended report are checked inside the write), `setStatus(expectFrom)`, `claimApproval`, `claim`, `settle` and `reopen` each change one thing. A real adapter implements these with a transaction or a precondition, never "read the report, change a copy, write it back": that rolls back a status or a claim written in between. Upload links must be create-only and one-time with the size and type fixed in their conditions (a Firebase or S3 signed PUT with `if-generation-match: 0` or `If-None-Match: *`), `discard` must delete a refused object, and `readUrl` links must expire after `ttlMs`.
 

package/dist/contract.mjs

@@ -14,12 +14,13 @@ export const CEILINGS = {
 export const STATUSES = ["on-phone", "received", "with-freeda", "planned", "waiting-on-owner", "being-made", "live", "sent-to-template", "filed", "not-now"];
 export const END = ["live", "sent-to-template", "filed", "not-now"];
 // actor: who PERFORMS this step (design section 7): sent by the person, received by the app, with Freeda by the Mac. A Helm on the owner's Mac posts straight into
-// the inbox, so a report may go from the phone to Freeda without the hosted app's "received".
+// the inbox, so a report may go from the phone to Freeda without the hosted app's "received". The owner may decline
+// ("not-now") before Freeda has a plan or before she asks: a report she cannot plan would otherwise have no exit.
 export const FLOW = {
     "on-phone": { actor: "person", next: ["received", "with-freeda"] },
     "received": { actor: "app", next: ["with-freeda"] },
-    "with-freeda": { actor: "mac", next: ["planned"] },
-    "planned": { actor: "freeda", next: ["waiting-on-owner", "being-made"] },
+    "with-freeda": { actor: "mac", next: ["planned", "not-now"] },
+    "planned": { actor: "freeda", next: ["waiting-on-owner", "being-made", "not-now"] },
     "waiting-on-owner": { actor: "owner", next: ["being-made", "filed", "not-now"] },
     "being-made": { actor: "freeda", next: ["live", "sent-to-template", "filed", "not-now"] },
     "live": { actor: "freeda", next: [] },

package/dist/server/handlers.d.ts

@@ -1,10 +1,13 @@
 import { type Limits } from './rate.ts';
+/** `by` is the actor (contract FLOW). `holder` is the maintainer whose Mac started or ended the work, written on a being-made
+ *  or end entry: the approval on such a report never lapses, and it is how the list and the claim name who has it. */
 export interface TimelineEntry {
     status: string;
     by: string;
     at: string;
     step?: string;
     note?: string;
+    holder?: string;
 }
 export interface FileState {
     pending?: {
@@ -155,6 +158,8 @@ export interface ReportHandlerOptions {
 export declare const LEASE_MS: number;
 export declare const BODY_CAP: number;
 export declare const APPROVAL_LEASE_MS: number;
+/** The approval's lease once the work has started or ended: in effect it never lapses (finite, so every store can keep it). */
+export declare const HELD_MS: number;
 export declare const READ_TTL_MS: number;
 export declare const VOICE_FILE_BYTES: number;
 /** A voice file may be this many bytes per declared second (768 kbit/s, generous for any recorder) plus a little slack: ten seconds cannot claim 25 MB. */

package/dist/server/handlers.js

@@ -23,6 +23,8 @@ const WORDS_MAX = 20_000;
 // A maximal report in Chinese or emoji fits; the whole is still a small fraction of the 4 MB no handler may exceed.
 export const BODY_CAP = 4 * WORDS_MAX * 4 + 64 * 1024;
 export const APPROVAL_LEASE_MS = 7 * 24 * 3600_000;
+/** The approval's lease once the work has started or ended: in effect it never lapses (finite, so every store can keep it). */
+export const HELD_MS = 100 * 365 * 24 * 3600_000;
 export const READ_TTL_MS = 5 * 60_000;
 export const VOICE_FILE_BYTES = 25 * 2 ** 20;
 /** A voice file may be this many bytes per declared second (768 kbit/s, generous for any recorder) plus a little slack: ten seconds cannot claim 25 MB. */
@@ -74,6 +76,15 @@ async function readBody(req, cap = BODY_CAP, optional = false) {
 }
 const iso = (ms) => new Date(ms).toISOString();
 const lastStatus = (r) => r.timeline[r.timeline.length - 1]?.status ?? 'received';
+/** Past asking the owner: the work has started or ended, and whoever holds the approval keeps it. */
+const PAST_ASKING = ['being-made', ...END];
+/** The maintainer named on the latest move that started or ended the work; none on a report from before 0.1.4. */
+const holderOf = (r) => {
+    for (let i = r.timeline.length - 1; i >= 0; i--)
+        if (r.timeline[i].holder)
+            return r.timeline[i].holder;
+    return undefined;
+};
 const str = (v, max) => (typeof v === 'string' && v.length <= max ? v : null);
 const fileNames = (r) => [
     ...(r.media ?? []).map((m) => m.file),
@@ -400,17 +411,36 @@ export function createReportHandlers(opts) {
             return signIn();
         const out = [];
         // A page, oldest first. Reports from before this maintainer was added are skipped when `maintainersSince` says so.
-        for (const r of await store.listOpenFor(by, { limit: limits.agentPage * 3, since: since(by) })) {
-            if (out.length >= limits.agentPage)
+        // A report another maintainer already closed is never offered: it is settled for this maintainer here, unseen, so
+        // it neither raises a notice on this Mac nor sits at the head of every page. Settling one frees a slot, so the
+        // store is asked again (a few times at most) until the page fills or nothing more was settled.
+        for (let round = 0; round < 4 && out.length < limits.agentPage; round++) {
+            const batch = await store.listOpenFor(by, { limit: limits.agentPage * 3, since: since(by) });
+            let settled = 0;
+            for (const r of batch) {
+                if (out.length >= limits.agentPage)
+                    break;
+                if (END.includes(lastStatus(r)) && holderOf(r) !== by) {
+                    await store.claim(r.id, by, LEASE_MS);
+                    if ((await store.settle(r.id, by, reportRevision(r))) === 'settled')
+                        settled++;
+                    continue;
+                }
+                // A report still waiting for its attachments is held back, so the Mac never copies half of one.
+                if (!complete(r) && now() - Date.parse(r.receivedAt) < INCOMPLETE_GRACE_MS)
+                    continue;
+                await store.claim(r.id, by, LEASE_MS);
+                out.push(r);
+            }
+            if (!settled || batch.length < limits.agentPage * 3)
                 break;
-            // A report still waiting for its attachments is held back, so the Mac never copies half of one.
-            if (!complete(r) && now() - Date.parse(r.receivedAt) < INCOMPLETE_GRACE_MS)
-                continue;
-            await store.claim(r.id, by, LEASE_MS);
-            out.push(r);
         }
         // `revision` is what this Mac is being shown; it goes back with the settle so a report that grew in between is not settled.
-        return json(200, { reports: out.map((r) => ({ ...r, revision: reportRevision(r) })) });
+        // `heldBy` names another maintainer whose Mac is making the report, so this Mac files it as taken.
+        return json(200, { reports: out.map((r) => {
+                const holder = lastStatus(r) === 'being-made' ? holderOf(r) : undefined;
+                return { ...r, revision: reportRevision(r), ...(holder && holder !== by ? { heldBy: holder } : {}) };
+            }) });
     }
     async function agentFile(req, id, file) {
         const m = wrongMethod(req, 'GET');
@@ -455,6 +485,19 @@ export function createReportHandlers(opts) {
         await tell({ type: 'settled', reportId: id });
         return json(200, { id, status: moves ? 'with-freeda' : lastStatus(r) });
     }
+    /** Takes (or renews) the approval for `by`. A closed report is never taken, by anyone: it answers who closed it. A
+     *  report being made stays with the Mac that started it. Taken for a move that starts or ends the work, or on a
+     *  report already being made, the lease is HELD_MS, so it does not lapse; before that, a week. Writes nothing when refused. */
+    async function takeApproval(r, by, to) {
+        const from = lastStatus(r);
+        const holder = holderOf(r);
+        if (END.includes(from))
+            return { closed: from, ...(holder ? { claimedBy: holder } : {}) };
+        if (from === 'being-made' && holder && holder !== by)
+            return { claimedBy: holder };
+        const lasting = from === 'being-made' || (to !== undefined && PAST_ASKING.includes(to));
+        return store.claimApproval(r.id, by, lasting ? HELD_MS : APPROVAL_LEASE_MS);
+    }
     async function agentClaimApproval(req, id) {
         const m = wrongMethod(req, 'POST');
         if (m)
@@ -465,9 +508,12 @@ export function createReportHandlers(opts) {
         const body = await readBody(req, BODY_CAP, true);
         if ('res' in body)
             return body.res;
-        if (!isReportId(id) || !(await store.get(id)))
+        const r = isReportId(id) ? await store.get(id) : null;
+        if (!r)
             return notFound();
-        const got = await store.claimApproval(id, by, APPROVAL_LEASE_MS);
+        const got = await takeApproval(r, by);
+        if ('closed' in got)
+            return json(409, { error: 'this suggestion is closed', closed: true, status: got.closed, ...(got.claimedBy ? { claimedBy: got.claimedBy } : {}) });
         return 'ok' in got ? json(200, { ok: true, claimedBy: by }) : json(409, { claimedBy: got.claimedBy });
     }
     async function agentReleaseApproval(req, id) {
@@ -511,14 +557,21 @@ export function createReportHandlers(opts) {
             return json(409, { error: `a report cannot go from ${from} to ${status}` });
         // Once the owner is being asked, the Mac that holds the approval decides what happens next. Leaving
         // waiting-on-owner, starting the work and ending it need the claim (taken here if nobody holds it).
-        if (from === 'waiting-on-owner' || status === 'being-made' || END.includes(status)) {
-            const c = await store.claimApproval(id, by, APPROVAL_LEASE_MS);
+        const needsApproval = from === 'waiting-on-owner' || PAST_ASKING.includes(status);
+        if (needsApproval) {
+            const c = await takeApproval(r, by, status);
             if (!('ok' in c))
-                return json(409, { error: 'another Mac holds the approval for this report', claimedBy: c.claimedBy });
+                return json(409, { error: 'another Mac holds the approval for this report', ...(c.claimedBy ? { claimedBy: c.claimedBy } : {}) });
         }
-        const moved = await store.setStatus(id, { status, by: FLOW[status].actor, at: iso(now()), ...(step ? { step } : {}), ...(note ? { note } : {}) }, from);
-        if (!moved)
+        // The maintainer is named on a move that starts or ends the work, so the hold is known from the report itself.
+        const holder = PAST_ASKING.includes(status) ? { holder: by } : {};
+        const moved = await store.setStatus(id, { status, by: FLOW[status].actor, at: iso(now()), ...(step ? { step } : {}), ...(note ? { note } : {}), ...holder }, from);
+        if (!moved) {
+            // The lasting lease was taken for a move that did not happen: bring it back to a week.
+            if (needsApproval && from !== 'being-made' && PAST_ASKING.includes(status))
+                await store.claimApproval(id, by, APPROVAL_LEASE_MS);
             return json(409, { error: 'the report changed while this was sent; read it again' });
+        }
         await tell({ type: 'status', reportId: id });
         return json(200, { id, status });
     }

package/dist/server/index.d.ts

@@ -1,4 +1,4 @@
-export { createReportHandlers, reportRevision, VOICE_BYTES_PER_SECOND, LEASE_MS, BODY_CAP, APPROVAL_LEASE_MS, READ_TTL_MS, INCOMPLETE_GRACE_MS, VOICE_FILE_BYTES } from './handlers.ts';
+export { createReportHandlers, reportRevision, VOICE_BYTES_PER_SECOND, LEASE_MS, BODY_CAP, APPROVAL_LEASE_MS, HELD_MS, READ_TTL_MS, INCOMPLETE_GRACE_MS, VOICE_FILE_BYTES } from './handlers.ts';
 export type { HostedStore, StoredReport, TimelineEntry, FileState, FollowUp, TellEvent, ReportHandlerOptions } from './handlers.ts';
 export { sniffType, sameType, canonicalType, ACCEPTED_TYPES } from './sniff.ts';
 export { effectiveLimits } from './rate.ts';

package/dist/server/index.js

@@ -1,5 +1,5 @@
 // "@supersuit/suggest-a-change/server": web-standard APIs only, no runtime dependency, nothing from react or the client.
-export { createReportHandlers, reportRevision, VOICE_BYTES_PER_SECOND, LEASE_MS, BODY_CAP, APPROVAL_LEASE_MS, READ_TTL_MS, INCOMPLETE_GRACE_MS, VOICE_FILE_BYTES } from './handlers.js';
+export { createReportHandlers, reportRevision, VOICE_BYTES_PER_SECOND, LEASE_MS, BODY_CAP, APPROVAL_LEASE_MS, HELD_MS, READ_TTL_MS, INCOMPLETE_GRACE_MS, VOICE_FILE_BYTES } from './handlers.js';
 export { sniffType, sameType, canonicalType, ACCEPTED_TYPES } from './sniff.js';
 export { effectiveLimits } from './rate.js';
 export { runStoreConformance, checks as conformanceChecks } from './conformance.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supersuit/suggest-a-change",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "The report format and flow behind a Suggest a change button: what a report is, who acts at each step, the screens, and the check every app runs. The contract has zero dependencies.",
   "type": "module",
   "bin": {

package/src/contract.mjs

@@ -18,12 +18,13 @@ export const STATUSES = ["on-phone", "received", "with-freeda", "planned", "wait
 export const END = ["live", "sent-to-template", "filed", "not-now"];
 
 // actor: who PERFORMS this step (design section 7): sent by the person, received by the app, with Freeda by the Mac. A Helm on the owner's Mac posts straight into
-// the inbox, so a report may go from the phone to Freeda without the hosted app's "received".
+// the inbox, so a report may go from the phone to Freeda without the hosted app's "received". The owner may decline
+// ("not-now") before Freeda has a plan or before she asks: a report she cannot plan would otherwise have no exit.
 export const FLOW = {
   "on-phone": { actor: "person", next: ["received", "with-freeda"] },
   "received": { actor: "app", next: ["with-freeda"] },
-  "with-freeda": { actor: "mac", next: ["planned"] },
-  "planned": { actor: "freeda", next: ["waiting-on-owner", "being-made"] },
+  "with-freeda": { actor: "mac", next: ["planned", "not-now"] },
+  "planned": { actor: "freeda", next: ["waiting-on-owner", "being-made", "not-now"] },
   "waiting-on-owner": { actor: "owner", next: ["being-made", "filed", "not-now"] },
   "being-made": { actor: "freeda", next: ["live", "sent-to-template", "filed", "not-now"] },
   "live": { actor: "freeda", next: [] },

package/src/server/handlers.ts

@@ -11,7 +11,9 @@ import { END, FLOW, STATUSES, isAcceptedMedia, isReportId, mayMove, validateRepo
 import { effectiveLimits, type Limits } from './rate.ts'
 import { ACCEPTED_TYPES, canonicalType, sameType } from './sniff.ts'
 
-export interface TimelineEntry { status: string; by: string; at: string; step?: string; note?: string }
+/** `by` is the actor (contract FLOW). `holder` is the maintainer whose Mac started or ended the work, written on a being-made
+ *  or end entry: the approval on such a report never lapses, and it is how the list and the claim name who has it. */
+export interface TimelineEntry { status: string; by: string; at: string; step?: string; note?: string; holder?: string }
 export interface FileState { pending?: { type: string; bytes: number; issuedAt?: number }; type?: string; bytes?: number; sha256?: string; at?: string }
 export interface FollowUp { followId: string; words: string; at: string; by: string; voice: { file: string; ms: number }[] }
 export interface StoredReport {
@@ -105,6 +107,8 @@ const WORDS_MAX = 20_000
 // A maximal report in Chinese or emoji fits; the whole is still a small fraction of the 4 MB no handler may exceed.
 export const BODY_CAP = 4 * WORDS_MAX * 4 + 64 * 1024
 export const APPROVAL_LEASE_MS = 7 * 24 * 3600_000
+/** The approval's lease once the work has started or ended: in effect it never lapses (finite, so every store can keep it). */
+export const HELD_MS = 100 * 365 * 24 * 3600_000
 export const READ_TTL_MS = 5 * 60_000
 export const VOICE_FILE_BYTES = 25 * 2 ** 20
 /** A voice file may be this many bytes per declared second (768 kbit/s, generous for any recorder) plus a little slack: ten seconds cannot claim 25 MB. */
@@ -149,6 +153,13 @@ async function readBody(req: Request, cap = BODY_CAP, optional = false): Promise
 
 const iso = (ms: number) => new Date(ms).toISOString()
 const lastStatus = (r: StoredReport) => r.timeline[r.timeline.length - 1]?.status ?? 'received'
+/** Past asking the owner: the work has started or ended, and whoever holds the approval keeps it. */
+const PAST_ASKING = ['being-made', ...END]
+/** The maintainer named on the latest move that started or ended the work; none on a report from before 0.1.4. */
+const holderOf = (r: StoredReport): string | undefined => {
+  for (let i = r.timeline.length - 1; i >= 0; i--) if (r.timeline[i].holder) return r.timeline[i].holder
+  return undefined
+}
 const str = (v: unknown, max: number): string | null => (typeof v === 'string' && v.length <= max ? v : null)
 const fileNames = (r: StoredReport): string[] => [
   ...((r.media as { file: string }[] | undefined) ?? []).map((m) => m.file),
@@ -382,15 +393,32 @@ export function createReportHandlers(opts: ReportHandlerOptions) {
     const by = await maintainerFor(req); if (!by) return signIn()
     const out: StoredReport[] = []
     // A page, oldest first. Reports from before this maintainer was added are skipped when `maintainersSince` says so.
-    for (const r of await store.listOpenFor(by, { limit: limits.agentPage * 3, since: since(by) })) {
-      if (out.length >= limits.agentPage) break
-      // A report still waiting for its attachments is held back, so the Mac never copies half of one.
-      if (!complete(r) && now() - Date.parse(r.receivedAt) < INCOMPLETE_GRACE_MS) continue
-      await store.claim(r.id, by, LEASE_MS)
-      out.push(r)
+    // A report another maintainer already closed is never offered: it is settled for this maintainer here, unseen, so
+    // it neither raises a notice on this Mac nor sits at the head of every page. Settling one frees a slot, so the
+    // store is asked again (a few times at most) until the page fills or nothing more was settled.
+    for (let round = 0; round < 4 && out.length < limits.agentPage; round++) {
+      const batch = await store.listOpenFor(by, { limit: limits.agentPage * 3, since: since(by) })
+      let settled = 0
+      for (const r of batch) {
+        if (out.length >= limits.agentPage) break
+        if (END.includes(lastStatus(r)) && holderOf(r) !== by) {
+          await store.claim(r.id, by, LEASE_MS)
+          if ((await store.settle(r.id, by, reportRevision(r))) === 'settled') settled++
+          continue
+        }
+        // A report still waiting for its attachments is held back, so the Mac never copies half of one.
+        if (!complete(r) && now() - Date.parse(r.receivedAt) < INCOMPLETE_GRACE_MS) continue
+        await store.claim(r.id, by, LEASE_MS)
+        out.push(r)
+      }
+      if (!settled || batch.length < limits.agentPage * 3) break
     }
     // `revision` is what this Mac is being shown; it goes back with the settle so a report that grew in between is not settled.
-    return json(200, { reports: out.map((r) => ({ ...r, revision: reportRevision(r) })) })
+    // `heldBy` names another maintainer whose Mac is making the report, so this Mac files it as taken.
+    return json(200, { reports: out.map((r) => {
+      const holder = lastStatus(r) === 'being-made' ? holderOf(r) : undefined
+      return { ...r, revision: reportRevision(r), ...(holder && holder !== by ? { heldBy: holder } : {}) }
+    }) })
   }
 
   async function agentFile(req: Request, id: string, file: string): Promise<Response> {
@@ -422,12 +450,26 @@ export function createReportHandlers(opts: ReportHandlerOptions) {
     return json(200, { id, status: moves ? 'with-freeda' : lastStatus(r) })
   }
 
+  /** Takes (or renews) the approval for `by`. A closed report is never taken, by anyone: it answers who closed it. A
+   *  report being made stays with the Mac that started it. Taken for a move that starts or ends the work, or on a
+   *  report already being made, the lease is HELD_MS, so it does not lapse; before that, a week. Writes nothing when refused. */
+  async function takeApproval(r: StoredReport, by: string, to?: string): Promise<{ ok: true } | { closed: string; claimedBy?: string } | { claimedBy: string }> {
+    const from = lastStatus(r)
+    const holder = holderOf(r)
+    if (END.includes(from)) return { closed: from, ...(holder ? { claimedBy: holder } : {}) }
+    if (from === 'being-made' && holder && holder !== by) return { claimedBy: holder }
+    const lasting = from === 'being-made' || (to !== undefined && PAST_ASKING.includes(to))
+    return store.claimApproval(r.id, by, lasting ? HELD_MS : APPROVAL_LEASE_MS)
+  }
+
   async function agentClaimApproval(req: Request, id: string): Promise<Response> {
     const m = wrongMethod(req, 'POST'); if (m) return m
     const by = await maintainerFor(req); if (!by) return signIn()
     const body = await readBody(req, BODY_CAP, true); if ('res' in body) return body.res
-    if (!isReportId(id) || !(await store.get(id))) return notFound()
-    const got = await store.claimApproval(id, by, APPROVAL_LEASE_MS)
+    const r = isReportId(id) ? await store.get(id) : null
+    if (!r) return notFound()
+    const got = await takeApproval(r, by)
+    if ('closed' in got) return json(409, { error: 'this suggestion is closed', closed: true, status: got.closed, ...(got.claimedBy ? { claimedBy: got.claimedBy } : {}) })
     return 'ok' in got ? json(200, { ok: true, claimedBy: by }) : json(409, { claimedBy: got.claimedBy })
   }
 
@@ -455,12 +497,19 @@ export function createReportHandlers(opts: ReportHandlerOptions) {
     if (!mayMove(from, status)) return json(409, { error: `a report cannot go from ${from} to ${status}` })
     // Once the owner is being asked, the Mac that holds the approval decides what happens next. Leaving
     // waiting-on-owner, starting the work and ending it need the claim (taken here if nobody holds it).
-    if (from === 'waiting-on-owner' || status === 'being-made' || END.includes(status)) {
-      const c = await store.claimApproval(id, by, APPROVAL_LEASE_MS)
-      if (!('ok' in c)) return json(409, { error: 'another Mac holds the approval for this report', claimedBy: c.claimedBy })
+    const needsApproval = from === 'waiting-on-owner' || PAST_ASKING.includes(status)
+    if (needsApproval) {
+      const c = await takeApproval(r, by, status)
+      if (!('ok' in c)) return json(409, { error: 'another Mac holds the approval for this report', ...(c.claimedBy ? { claimedBy: c.claimedBy } : {}) })
+    }
+    // The maintainer is named on a move that starts or ends the work, so the hold is known from the report itself.
+    const holder = PAST_ASKING.includes(status) ? { holder: by } : {}
+    const moved = await store.setStatus(id, { status, by: FLOW[status as keyof typeof FLOW].actor, at: iso(now()), ...(step ? { step } : {}), ...(note ? { note } : {}), ...holder }, from)
+    if (!moved) {
+      // The lasting lease was taken for a move that did not happen: bring it back to a week.
+      if (needsApproval && from !== 'being-made' && PAST_ASKING.includes(status)) await store.claimApproval(id, by, APPROVAL_LEASE_MS)
+      return json(409, { error: 'the report changed while this was sent; read it again' })
     }
-    const moved = await store.setStatus(id, { status, by: FLOW[status as keyof typeof FLOW].actor, at: iso(now()), ...(step ? { step } : {}), ...(note ? { note } : {}) }, from)
-    if (!moved) return json(409, { error: 'the report changed while this was sent; read it again' })
     await tell({ type: 'status', reportId: id })
     return json(200, { id, status })
   }

package/src/server/index.ts

@@ -1,5 +1,5 @@
 // "@supersuit/suggest-a-change/server": web-standard APIs only, no runtime dependency, nothing from react or the client.
-export { createReportHandlers, reportRevision, VOICE_BYTES_PER_SECOND, LEASE_MS, BODY_CAP, APPROVAL_LEASE_MS, READ_TTL_MS, INCOMPLETE_GRACE_MS, VOICE_FILE_BYTES } from './handlers.ts'
+export { createReportHandlers, reportRevision, VOICE_BYTES_PER_SECOND, LEASE_MS, BODY_CAP, APPROVAL_LEASE_MS, HELD_MS, READ_TTL_MS, INCOMPLETE_GRACE_MS, VOICE_FILE_BYTES } from './handlers.ts'
 export type { HostedStore, StoredReport, TimelineEntry, FileState, FollowUp, TellEvent, ReportHandlerOptions } from './handlers.ts'
 export { sniffType, sameType, canonicalType, ACCEPTED_TYPES } from './sniff.ts'
 export { effectiveLimits } from './rate.ts'