The agent can keep a private note on a deal that never reaches a client #308

Each deal now has a "Private note" box on its page (up to 500 characters). The note shows only there and never reaches a draft, timeline or handout.

The full bun test run had one failure when I ran it: a speed test ("the clock with closed deals answers within budget…") failed in the full run but passed when I reran speed.test.ts alone. A hand-built deal in partycontact.test.ts lacked the new note field, so I gave it one. I did not rerun the whole suite after that.

What changed

• Storage: a new last migration adds deal.note (text, at most 500 characters), and migrations.pin.json pins it. migrations.test.ts now excludes it when it rebuilds an older database.
• Saving: setDealNote in src/deals.ts asks permit(update) on deal and is audited as deal.note. Line breaks are kept. Any other control character, or more than 500 characters, is refused. Empty clears the note.
• Doors:

- Page: a plain form posting to POST /deals/:id/note. It goes through the same same-origin door as every other form, and the output is escaped. - API: PATCH /api/deals/:id takes note, alone or together with other fields. A bad note is a 400 with field note before anything else is applied. - OpenAPI: the deal schema and the PATCH body gain note, and contract/openapi.json is re-emitted.

• Export and import: the note travels as private_note. Import validates it and refuses a bad one with a 422 naming the field.
• Activity page: it words deal.note.
• Docs: README has one line and docs/TECHNICAL.md has the details.
• Tests: src/dealnote.test.ts covers the PATCH rules and audit row, the form, escaping and the export and import round trip. A note containing the word ZEBRAWORD is checked for absence from the client timeline, broker file, calendar file, sheets, This week, the clock, the spreadsheet export, the reminder drafts and the status update.

Policy: no contract cell changed. The existing deal update cell is user, so any signed-in user who can reach a deal can overwrite its note, as they can its address.

Not done

• No MCP tool or terminal command for the deal note; the issue didn't ask for either.
• A refused form save comes back as a notice rather than keeping the typed text.

Checks not run

• scripts/gate.ts and design-lint.ts: neither exists in this repo. I ran bun run lint:design instead and it was clean.
• tsc: there is no tsconfig.json, so bun x tsc --noEmit has nothing to check.

To try it: open any deal, type in "Private note", save, then open the client timeline and the broker file; the note isn't there.

🤖 Generated with Claude Code

Closes #306

Each deal now has a "Private note" box on its page (up to 500 characters). The note shows only there and never reaches a draft, timeline or handout.

The full bun test run had one failure when I ran it: a speed test ("the clock with closed deals answers within budget…") failed in the full run but passed when I reran speed.test.ts alone. A hand-built deal in partycontact.test.ts lacked the new note field, so I gave it one. I did not rerun the whole suite after that.

What changed

• Storage: a new last migration adds deal.note (text, at most 500 characters), and migrations.pin.json pins it. migrations.test.ts now excludes it when it rebuilds an older database.
• Saving: setDealNote in src/deals.ts asks permit(update) on deal and is audited as deal.note. Line breaks are kept. Any other control character, or more than 500 characters, is refused. Empty clears the note.
• Doors:

- Page: a plain form posting to POST /deals/:id/note. It goes through the same same-origin door as every other form, and the output is escaped. - API: PATCH /api/deals/:id takes note, alone or together with other fields. A bad note is a 400 with field note before anything else is applied. - OpenAPI: the deal schema and the PATCH body gain note, and contract/openapi.json is re-emitted.

• Export and import: the note travels as private_note. Import validates it and refuses a bad one with a 422 naming the field.
• Activity page: it words deal.note.
• Docs: README has one line and docs/TECHNICAL.md has the details.
• Tests: src/dealnote.test.ts covers the PATCH rules and audit row, the form, escaping and the export and import round trip. A note containing the word ZEBRAWORD is checked for absence from the client timeline, broker file, calendar file, sheets, This week, the clock, the spreadsheet export, the reminder drafts and the status update.

Policy: no contract cell changed. The existing deal update cell is user, so any signed-in user who can reach a deal can overwrite its note, as they can its address.

Not done

• No MCP tool or terminal command for the deal note; the issue didn't ask for either.
• A refused form save comes back as a notice rather than keeping the typed text.

Checks not run

• scripts/gate.ts and design-lint.ts: neither exists in this repo. I ran bun run lint:design instead and it was clean.
• tsc: there is no tsconfig.json, so bun x tsc --noEmit has nothing to check.

To try it: open any deal, type in "Private note", save, then open the client timeline and the broker file; the note isn't there.

🤖 Generated with Claude Code

The private note can now be read and written in the terminal and over MCP, and the smaller review points are fixed too. The full bun test run is green (813 pass). The first full run had two timing-budget failures that did not reproduce when I reran those files alone, or on a second full run.

• Terminal: open a deal and press K. The prompt shows the current note and takes a new one; an empty line clears it. The deal header now shows Private note: …. The key calls setDealNote, which asks permit(update). Reading goes through openDeal, which reads the deal through permit like the page does. A write emits deal.changed, so web viewers update live. A test in terminal.test.ts covers setting, showing, clearing, the deal.note audit row, and a guest being refused.
• MCP: new set_deal_note tool, with the same 500-character rule. src/dealnote.test.ts tests it, and the tool list in server.test.ts includes it.
• Docs: the README line is rewrapped and now names K. docs/TECHNICAL.md lists the terminal key and the MCP tool.
• Form test: a guest's post is asserted as a 303 that leaves the note unchanged.
• Where I disagree: you asked for a signed-in non-owner case to be asserted as refused. contract.json sets deal update to user, so another signed-in user is allowed, exactly as they can already edit the address. The test asserts that 303 and documents it. Making it author-only would change a contract cell, and I won't do that without the issue asking.

I merged main into the branch, resolved the four conflicts, and pushed. The full bun test run passes (820 pass, 0 fail).

• src/db.ts: the new main migration (deadline_move.undo) stays where main put it. My deal.note migration comes after it, still last.
• src/migrations.pin.json: pins run in the same order — main's new hash, then mine.
• src/migrations.test.ts: the older-database filter now excludes both new migrations.
• src/terminal.ts: I took main's key help, which adds U undo move, and kept K private note on the deal-view line.

No contract cell changed.