Skip to content

Latest commit

 

History

History
101 lines (96 loc) · 31.5 KB

ASSUMPTIONS.md

File metadata and controls

101 lines (96 loc) · 31.5 KB

Assumptions Log

Every decision taken while turning the original design notes into the implementation spec and the implementation, with rationale. Numbered so code comments and the plan can cite them (A1, A2, ...). Decisions the user made explicitly (2026-09-28 Q&A) are marked [user].

Decisions from the user

  • U1 [user] Stack: TypeScript on Node 24 for both server and CLI. Fastify + node-postgres.
  • U2 [user] skill/ holds both a Claude Code plugin (hooks + /mokkan) and a Codex skill, both wrapping one mokkan CLI.
  • U3 [user] Acknowledgment is explicit: the user runs /mokkan ack <id> (or ack all) for every viewed reminder. Hooks never auto-acknowledge.
  • U4 [user] Deployment target is local dev only: HTTP on 127.0.0.1, Postgres in Docker. HTTPS is left to a reverse proxy later.
  • U5 [user] Postgres row-level security is used if it is fast enough (perf gate in spec §3).
  • U6 [user] Emails are mocked (no SMTP).
  • U7 [user] No UI testing inside Codex; the user tests that by hand.
  • U8 [user, 2026-09-29] Status line: show the most recently added reminder plus "+N more"; show reminder text by default; a due reminder unseen for more than 15 minutes is "overdue" (red); Codex is covered via a tmux status-right mode because Codex has no command-backed status line.
  • U9 [user, 2026-09-29] Prepaid credits. EUR 5 buys 500 credits (1 credit = 1 cent); packs are Stripe prices found by lookup_key, credits from the price's metadata.credits, default pack credits_500. Push = 1 credit; every 3rd edit = 1 credit; a scheduled email = 1 credit. pop, dequeue, ack, deliver, list, pending, heartbeat, /me and billing reads are free.
  • U10 [user, 2026-09-29] PATCH /reminders/:id edits text and/or due_at (null clears it); one successful PATCH is one edit; no reordering.
  • U11 [user, 2026-09-29] The email credit is debited when the scheduler actually sends (claim and debit in one transaction) and refunded if the send fails. Pushing with any due_at needs a balance of at least push cost + email cost × (outstanding + 1), where outstanding = reminders with a due time that have not been emailed and are not acknowledged (scheduled, due, or shown in a session but not yet acknowledged; mokkan ack releases the reserve; the edited one excluded), but debits only the push; setting a due time via PATCH needs the same reserve (plus that edit's own debit); the 402 required reports that number; the email debit may take the balance below zero, so a promised email is never dropped. Escalation emails are charged the same way; a reminder is emailed at most once.
  • U12 [user, 2026-09-29] At zero credits paid actions answer 402 insufficient_credits; reading and completing stay free. When a debit takes the balance from above 0 to 0 or below, one "out of credits" email is sent (re-armed by a grant or purchase).
  • U13 [user, 2026-09-29] 50 starter credits on sign-up (STARTER_CREDITS, 0 disables) as a grant ledger row. Credits never expire; refunds are manual in the Stripe Dashboard and the webhook removes the refunded share.
  • U14 [user, 2026-09-29] VAT via config flag STRIPE_AUTOMATIC_TAX (default false). Mailer is generic SMTP via nodemailer (MAILER=smtp, set up for Zoho); MAILER=mock stays for tests and dev.
  • U16 [user, 2026-09-29] Release-gate fixes. The status line runs plain node when command -v node resolves to the same real file as the running binary, else its absolute path (README says so). From Claude Code (--exit-zero, i.e. /mokkan or /mokkan:mokkan) plain statusline sets up Claude Code only (removal still takes out mokkan's own tmux block). Auto setup skips tmux when the config has its own status-right or a TPM run line and prints the #(…) to combine; explicit --tmux then needs --force. Configure-vs-render depends on stdin being a terminal only.
  • U17 [user, 2026-09-29] The public repository will be github.com/vicmpen/mokkan, published later from a fresh squashed history; vicmpen/mokkan-skill stays private. The marketplace name stays mokkan. The support address is the Zoho sending address on mokkan.dev (the one on Stripe receipts).
  • U15 [user, 2026-09-29] mokkan statusline configures the status line (Claude Code's settings.json, plus a marked tmux block for Codex and terminals) and mokkan statusline --render renders it. Codex's own config is not touched: its footer cannot run a command. Supersedes A33.
  • U19 [user, 2026-10-05] Notifications (mokkan notify) are read-only: a poll calls GET /reminders/pending and nothing else, with no heartbeat and no deliver. An unacknowledged scheduled reminder still escalates to email, so a notification nobody saw loses nothing.
  • U20 [user, 2026-10-05] mokkan notify setup detects the platform and whether a desktop session exists, then offers the best setup it finds: a launchd agent on macOS, a systemd user timer on Linux with a desktop and systemd, XDG autostart on Linux with a desktop but no systemd, and only the prompt hook on a headless machine or WSL. It asks before each step.
  • U21 [user, 2026-10-05] The prompt hook supports zsh, bash (including macOS's bash 3.2) and fish. Shells, desktop backends and agents are registries of small modules with a shared contract test, so other systems can come as contributions (CONTRIBUTING.md, a PR template, an issue form asking for mokkan notify doctor).
  • U22 [user, 2026-10-05] The terminal escape over SSH (OSC 9/777/99) is opt-in: the osc setting is off by default, and when on, the shell sends it only when $SSH_CONNECTION is set.
  • U23 [user, 2026-10-05] Only scheduled reminders notify: due_at set and passed, not acknowledged, from pending.due and pending.awaiting_ack. Plain pushes never do, and a reminder already shown in a session or emailed still counts until it is acked. Every open shell prints the set once per change, remembered in a shell variable rather than a shared file.

Assumptions I made

  • A1 Popped/dequeued items move to a done history (soft delete) rather than being deleted. The user's answer chose explicit ack but did not object to the history default; history costs one column and makes accidental pops recoverable. If wrong: switch pop/dequeue to DELETE, one-line change in the service.
  • A2 Ports: Postgres on 127.0.0.1:5439 (5432–5434 are taken by other projects' containers on this machine), API on 127.0.0.1:8787. Both overridable by env.
  • A3 Lifecycle extends the design's three states (due → delivered → acknowledged) with scheduled (future due_at, not yet on the list) and done (popped). A future reminder is not "due", and the design's "done history" open question needs a terminal state. The three design states keep their exact meaning.
  • A4 A pushed item (no due_at) starts in state due: it is on the list now. It is shown by the next hook run and marked delivered; it then waits for explicit ack (U3). It still stays on the stack after ack until popped/dequeued; ack only means "I saw it".
  • A5 RLS applies to reminders and tokens (the account-scoped data). accounts, otps, rate_limits, outbox are not under RLS because login/OTP/rate-limit lookups happen before an account context exists. Token lookup by hash goes through a SECURITY DEFINER function so the app role never reads the tokens table directly. If the perf gate (200 pops, mean < 20 ms) fails, RLS is dropped in favor of explicit WHERE account_id and this line is updated.
  • A6 Two DB roles: the Docker superuser mokkan runs migrations; the API connects as mokkan_app (LOGIN, no BYPASSRLS, not table owner) so RLS is actually enforced. Two connection strings in .env.
  • A7 Email escalation applies only to scheduled reminders (due_at set). Pushed list items are never emailed: emailing every un-acked list item after 3 minutes would be spam, and the design's routing section talks about "when a reminder fires".
  • A8 The scheduler lives in the server process (design §3 says "the server holds due_at ... and a scheduler checks for due items"). The client-side "background watcher" therefore does not decide email routing; mokkan watch is a foreground poller that sends heartbeats, prints due reminders to the terminal, and marks them delivered. Packaging as a daemon (systemd/launchd) is documented, not automated, because it cannot be tested here.
  • A9 Design's "optionally both" routing is expressed as ACK_GRACE_SECONDS=0 (email immediately after in-session delivery) rather than a separate mode flag. Fewer code paths.
  • A10 Optimistic concurrency uses a per-account list_version counter and an optional expected_version on pop/dequeue/ack (409 stale on mismatch). Push is idempotent via an optional client_id instead of a version, because a push never conflicts with another push. Atomicity of pop/dequeue is guaranteed by the single-statement UPDATE ... WHERE id = (SELECT ... FOR UPDATE SKIP LOCKED) form regardless of versions.
  • A11 Tokens are opaque random strings stored hashed, not JWTs: revocation and rotation are then trivial and there is no signing key to manage. Access token 24 h, refresh 90 days, rotation on refresh with family revocation on reuse (design asked for expiry + refresh; exact numbers are mine).
  • A12 Password hashing uses argon2id via @node-rs/argon2 (prebuilt binary, no native toolchain needed). Minimum password length 10.
  • A13 OTP is 6 digits, 10 minutes, 5 attempts, 3 sends per email per 15 minutes; login 10 attempts per email per 15 minutes; 20 auth calls per IP per 15 minutes. Design said "five to ten minutes" and "rate-limited"; numbers are mine.
  • A14 register/start returns 409 when the email already has an account instead of a silent 202. This is a personal tool; the friendlier error beats enumeration resistance.
  • A15 The Stop hook surfaces reminders by returning {"decision":"block","reason":...} so Claude relays them in its next reply, plus a systemMessage for the user. Plain stdout from a Stop hook is not shown to the model. It blocks only when there are newly due reminders and stop_hook_active is false, so it cannot loop. If this proves annoying, switch to systemMessage only.
  • A16 The /mokkan slash command uses Claude Code's ! bash expansion (allowed-tools: Bash(mokkan:*)) so the CLI runs deterministically before the model sees anything, and the model is told to relay output verbatim. register/login need hidden input; run from a terminal, the slash command only starts the OTP flow.
  • A17 Codex has no stable hook mechanism in the installed version (0.106), so the Codex skill instructs the agent to call mokkan heartbeat and mokkan pending at task start/end. Installed by symlink to ~/.codex/skills/mokkan. Untested beyond lint (U7).
  • A18 The CLI credentials live at $XDG_CONFIG_HOME/mokkan/credentials.json (default ~/.config/mokkan), dir 0700 file 0600, and the CLI refuses to run if the file is group/world readable. Rotation policy: refresh rotates the refresh token; mokkan logout revokes the family.
  • A19 Tests run against the real Docker Postgres (no in-memory fake), and the scheduler is driven with an explicit now so tests never sleep. The end-to-end script is bash and asserts on the outbox.
  • A20 The repo was initialized as a git repository (main) because the workflow commits per task. No remote is configured.
  • A21 Mock emails are written to an outbox table and to server/outbox.jsonl, exposed via GET /dev/outbox only when MAILER=mock. This is how the OTP is read during registration in dev.
  • A22 Heartbeat "recent" means within 300 s. Stop hooks fire on every reply so a live session refreshes far more often than that.
  • A23 Duration syntax for mokkan in: Ns, Nm, Nh, Nd and combinations like 1h30m. No natural-language dates.
  • A24 The list output orders top-of-stack first (highest position). pop = top, dequeue = bottom, matching the design's LIFO/FIFO description.
  • A25 tokens.last_used_at (listed in the spec's data model) is omitted from the schema: nothing reads it, and updating it on every request would add a write per call. /me lives in auth/routes.ts rather than delivery/routes.ts; cosmetic. RLS is both ENABLED and FORCED on reminders and tokens; the Docker owner role is a superuser and bypasses RLS regardless, which is why the scheduler uses the admin pool (A6).
  • A26 Refresh rotation revokes the whole token family, including the still-valid access token. Two CLI processes refreshing the same family at the same instant (e.g. a Stop hook and a /mokkan command inside the 1-hour pre-expiry window) trip reuse detection and force a re-login. Chosen because reuse detection is worth more than that rare inconvenience; the pre-emptive refresh window keeps it rare. Processes on one machine no longer trip it (A28); it remains only for two different machines using the same tokens (e.g. a copied credentials.json). Separate logins start separate families and never interfere.
  • A27 The scheduler records email_sent_at unconditionally after sending, even if a hook delivered the reminder in-session between the scheduler's SELECT and UPDATE, so a reminder can never be emailed twice.
  • A28 Every mokkan process on a machine (the hooks of each Claude Code session, mokkan watch, commands) shares one credentials.json, and the server stays strict about refresh-token reuse (A26). So before any refresh (pre-emptive or after a 401) the CLI re-reads the file and, if another process already rotated the refresh token, adopts the stored tokens and retries instead of refreshing. The re-read, refresh and save run under an exclusive lock file credentials.json.lock (created with open(..., 'wx'), polled every 50 ms for up to 5 s, removed by its owner in finally; a lock older than 30 s is treated as left over from a crash and removed). When a refresh token is rejected anyway (expired, revoked, logged out elsewhere), the CLI removes the dead credentials file and says Session expired on this machine; run: mokkan login; hooks log that once, then log "Not logged in" at most hourly (marker file hook.log.notified).
  • A29 mokkan statusline fetches GET /reminders?scope=all (no new server endpoint). "Last added" = newest created_at among reminders not yet popped/dequeued, acknowledged and scheduled ones included (they are still on the list, A4); ties go to the top of the stack. "+N more" counts the rest of that set. Urgency survives as colour, classified against the local clock at render time: red if any reminder is unseen (due, or scheduled past its time) for more than the grace period, yellow if any is unseen, dim if only delivered ones await ack. A delivered reminder is never "overdue": a session already showed it.
  • A30 The status cache lives next to the credentials ($XDG_CONFIG_HOME/mokkan/status.json, 0600), not in $XDG_CACHE_HOME, because it holds reminder text and so tests stay inside one temp dir. The TTL is measured from the last refresh attempt, so a down server is retried once per TTL, not on every render.
  • A31 Invalidation deletes the cache after push/pop/dequeue/deliver/ack/login/register/logout (onListChanged in MokkanClient). A background refresh that started before such a change can rewrite slightly old data; that is bounded by the TTL (30 s) and accepted rather than adding version checks.
  • A32 The status line does not send heartbeats or mark anything delivered: showing a count is not delivering, and a timer-driven heartbeat would keep an idle machine "active" and suppress email escalation.
  • A33 (superseded by U15 and A37) install.sh printed the Claude Code statusLine and tmux snippets and never wrote settings.json or .tmux.conf. It still writes neither; it now tells the user to run mokkan statusline, which writes them on request.
  • A34 The CLI's default server is now https://api.mokkan.dev (was http://127.0.0.1:8787, A2/U4), because credits and Stripe Checkout need a public HTTPS server. MOKKAN_SERVER_URL and the server_url saved in credentials.json still win, so local development sets MOKKAN_SERVER_URL=http://127.0.0.1:8787. An existing login keeps the server it was made against.
  • A35 mokkan edit <n|id> takes the list number from mokkan list (active list, top first; --all uses the mokkan list --all numbering) when the argument is 1 to 3 digits: that is always a list number, and a number out of range is an error, never an id prefix. Anything else is an id prefix (as for ack), resolved against all non-done reminders. The new text is positional (mokkan edit 2 call mom), with --text as an alias (not both). It sends the list version as expected_version and retries once on a stale version, like ack. At most one of --in, --at, --clear-due may be given, plus text; at least one change is required. Combining changes in one call matters because every call is one edit and every 3rd edit costs a credit.
  • A36 Exit code 3 means insufficient credits (402). The skill docs tell agents to relay mokkan buy to the user and not to retry or buy themselves; buying needs a human and a browser.
  • A37 mokkan statusline (setup) rules. Only one status line can exist and it may be the user's own, so: (1) a Claude Code statusLine is "mokkan's" only when its command is nothing but [node] <path ending in mokkan, mokkan.mjs, or a cli.js/cli.mjs under a path containing "mokkan"> statusline [render flags] (no pipes, ;, $(), quoting tricks); anything else is foreign and is never replaced without --force, and a foreign command that calls mokkan statusline gets a hint to add --render. (2) mokkan's own entry is rewritten to <process.execPath> <cli> statusline --render, keeping its other keys (padding, a custom refreshInterval; default 30); equal JSON means "already configured" and nothing is written. (3) Writes are atomic (temp file + rename, through a symlink to its target, same mode) after a <file>.mokkan-bak-<UTC yyyymmddThhmmssZ> backup (-1, -2 … on collision); invalid JSON or a non-object is refused. (4) tmux changes only the marked block (appended after a blank line, replaced in place, removed with that blank line); an incomplete block is refused; the user's own status-right lines stay and are pointed out. (5) Without a target flag Claude Code is set up only if its config dir exists and tmux only if tmux is on PATH (PATH is searched, tmux is never run); "reload tmux" is printed as a hint whenever the block changed, without checking whether a server runs. (6) A CLI whose realpath lies under ~/.claude/plugins/cache or $CLAUDE_CONFIG_DIR/plugins/cache is copied (0755, atomically, only when the bytes differ) to ${XDG_DATA_HOME:-~/.local/share}/mokkan/mokkan.mjs, which the status line runs; mokkan hook session-start refreshes that copy when it exists and never creates it. (7) Compatibility: any render flag (--render, --format, --no-text, --width, --ttl, --grace, --refresh) means render, so old tmux snippets keep working; the plain command with no arguments, no TTY and no --exit-zero, while settings.json's statusLine is mokkan's, is Claude Code running an old config: it migrates that one setting to --render (once; afterwards it is a read of settings.json) and renders, never touching tmux. Consequence: an agent without a TTY (Codex) must pass a target flag (mokkan statusline --tmux) to configure; the skill docs say so.
  • A38 The Claude Code plugin ships the CLI as one committed esbuild bundle, claude-plugin/scripts/mokkan.mjs (ESM, node20, only node: imports). Plugins are copied from git into the plugin cache without running a build, and the status line's stable copy (A37) works only for a single file. It is not placed in bin/, because claude.ai and Cowork reject plugins that have a top-level bin/. npm run check:bundle and test/bundle.test.ts rebuild it in memory and fail when the committed file differs. The npm package keeps shipping the tsc output in dist/.
  • A39 The plugin's /mokkan command became the skill claude-plugin/skills/mokkan/SKILL.md, invoked as /mokkan:mokkan, so there is one entry and no name clash. The docs state that Claude Code substitutes ${CLAUDE_PLUGIN_ROOT} in a plugin skill's body, including in ! lines, and in its allowed-tools Bash rules. The skill therefore runs node ${CLAUDE_PLUGIN_ROOT}/scripts/mokkan.mjs --argline "$ARGUMENTS" --exit-zero and pre-approves exactly that prefix. The path is unquoted, as in the docs' example, so that the permission rule matches the command text. An install path that contains spaces would break it. There is no PATH fallback in the ! line, because a compound shell line would not match a simple rule. The PATH-based user command moved to claude-command/mokkan.md, which install.sh links as /mokkan. A test keeps its body identical to the skill's except for the run line.
  • A40 The hook scripts try the plugin bundle first, then a dev checkout's dist/cli.js, then mokkan on PATH. Running the bundle by its path keeps process.argv[1] inside the plugin cache, so the SessionStart hook can refresh the stable copy. A dev checkout that has the plugin loaded with --plugin-dir now runs the committed bundle rather than dist/.
  • A41 engines.node is >=20.3.0, the real minimum: AbortSignal.any needs 20.3. The previous >=24 came from the dev machine. The bundle targets node20. Nothing has been tested on Node 20 itself. CI runs Node 22.
  • A42 [user, 2026-10-05] Design notes, plans, research and this decision log are committed to the private development repository but never published: tools/export-public.sh leaves out docs/ (all of it, whatever the subfolder), ASSUMPTIONS.md, .impeccable/, .superpowers/ and .claude/, and the npm files whitelist (dist/**/*.js, codex/, claude-command/, CHANGELOG.md, plus README, LICENSE and package.json) keeps them out of the package. Public material for contributors goes in CONTRIBUTING.md. Until 2026-10-05 only docs/internal/ was left out, so the 0.3.1 export published the TUI spec and plan (docs/superpowers/); the next export removes them from the public tree, and they remain only in its history.
  • A43 Plain mokkan statusline with stdin not a terminal and without --exit-zero never runs the setup (it is most likely a status bar refresh): an old mokkan statusLine is migrated to --render and rendered; otherwise it prints one line and exits 0. A failed migration (read-only settings.json) is recorded in ~/.config/mokkan/statusline-migrate-failed and not retried for 24 h.
  • A44 File edits write a temp file first, then take the backup, then rename; a failed rename deletes its backup, and the file is re-read just before the rename so a concurrent write by Claude Code is not overwritten (the command then asks to run again).
  • A45 mokkan statusline refuses to point a status line at a CLI inside npm's _npx cache (--remove still works from there). Once a tmux config has mokkan's block, later runs update it without --force (the user opted in). --remove deletes the stable plugin copy when neither settings.json nor the tmux config mentions it any more.
  • A46 The plugin skill quotes "${CLAUDE_PLUGIN_ROOT}/scripts/mokkan.mjs" in both the ! line and allowed-tools (both must match; verified live by the reviewer with spaced and plain paths). The guardrails (never pass --force, logout or buy unless the user typed them) are in description:, which the model reads before the command runs. The plugin skill writes /mokkan:mokkan …, the user-level command /mokkan ….
  • U18 [user, 2026-09-29] npm rejected the unscoped name mokkan as too similar to morgan. The package is published as @vicmpen/mokkan-cli (public, publishConfig.access), still installing the mokkan command; the Claude Code plugin and marketplace keep the name mokkan.
  • A47 [user, 2026-09-30] The terminal UI is a separate subcommand, mokkan ui; bare mokkan keeps printing the list. It is hand-rolled on Node built-ins (raw mode, ANSI escapes, a pure render function) rather than Ink, because the plugin bundle must stay a small single file: the status line executes it every 30 seconds.
  • A48 [user, 2026-09-30] Reminders in state due that the TUI shows are marked delivered, and every refresh (on start, every 10 s, after each action) sends a heartbeat with source ui, exactly like the hooks and mokkan watch. Pop, dequeue, ack of the selected reminder and edit send the list version on screen; a 409 stale refreshes and asks to try again. After deliver the list is fetched again and its version adopted, so a pop right after delivery is not stale.
  • A49 [user, 2026-09-30] e edits text and t edits the time as two separate PATCH calls (two edits). b opens Stripe Checkout with the same URL check as mokkan buy. Without credentials mokkan ui opens on a login screen and a lost session returns to it; register stays a CLI command (once per account, a one-time-code wizard).
  • A50 Overdue in the TUI is the status line's rule (due and unseen for more than DEFAULT_GRACE_MINUTES). Bracketed paste is enabled: pasted text arrives as one paste key that only input fields accept, so it can never run commands. Display width is best effort (wide CJK ranges, emoji blocks, U+FE0F). Ctrl-C quits from every mode; Esc quits only from the login screen.
  • A51 [user, 2026-10-02] 0.3.0 removes the status line (render, setup, cache, stable CLI copy; U8, U15, U16, A29, A30, A32, A37, A43, A45 and the status-line half of A40 no longer apply). mokkan statusline remains for one release as a stub: without --remove it prints nothing when stdout is not a terminal (an old status bar keeps running it harmlessly) and one hint when it is; --remove undoes a 0.2.0 setup. The TUI keeps the shared formatting helpers in src/text.ts.
  • A52 [user, 2026-10-02] The Claude Code pane is part of the plugin, as a function-hooks module (claude-plugin/hooks/pane.tsx, named under modules in the same hooks.json as the shell hooks; its $.state contract is claude-plugin/types/index.d.ts). It runs the plugin's own bundle ($.plugin.root/scripts/mokkan.mjs), then a dev checkout's dist/cli.js, then mokkan on PATH. npm run test:plugin validates and tests it with the claude CLI; vitest does not load it. Done and ack stay two acts in the pane too: a finishes (or reopens), k acknowledges.
  • A53 The notify stamp records the time of the last poll attempt, written before the network call (the A30 rule), so a server that is down is retried once per interval and never makes every prompt start node. The agent and every shell share the stamp and poll.lock, so a machine makes at most one pending call per interval.
  • A54 A reminder id is marked notified in notified.json only when the desktop notifier exits 0. A failure counts as an attempt and the id is given up after 3, so a notification daemon that is not up yet (the timer's first run at boot) does not lose the popup. Ids that are no longer notifiable are pruned.
  • A55 More than 3 new reminders in one poll become one summary notification ("4 reminders due"), whose result counts for each of them.
  • A56 shell.txt and the notifications show the due time as a local clock time (HH:MM today, ddd HH:MM within 6 days, else the date), never a relative time: "5m ago" would change every poll and make every shell print again each minute.
  • A57 logout, session expiry and delete-account remove the reminder text in notify/ (removeNotifyState) but keep the generated init.<shell> scripts, so the prompt hook resumes after the next login. notify remove deletes them too and keeps config.json.
  • A58 The node baked into the agent and the snippet is the first node on PATH when it resolves to the running binary, else process.execPath: a PATH entry such as /opt/homebrew/bin/node survives upgrades, a versioned Cellar path does not (the rule U16 had for the status line). The CLI path is the realpath of the running cli.js. Only notify setup (and on/off, run from a shell) choose these paths; a poll that regenerates init.<shell> keeps the paths already in it, because the agent runs with launchd's or systemd's PATH, where the stable node is not found.
  • A59 notify setup refuses to run from a CLI whose path contains /plugins/cache/, /.claude/plugins/ or /_npx/, because those change with every update (the rule A45 had); it asks for npm i -g @vicmpen/mokkan-cli or install.sh. shell init only warns there.
  • A60 The gdbus backend writes every argument as a typed GVariant literal (strings double-quoted with \, " and control characters escaped), because gdbus call parses its arguments as GVariant text and would change plain text such as 'x', 123 or true. Verified against a fake notification service under dbus-run-session.
  • A61 The systemd agent runs daemon-reload, enable and then restart on the timer rather than enable --now, because a running timer keeps its old OnUnitActiveSec until restarted; this way a new interval applies when setup runs again. Identical files with the timer enabled and active are left alone.
  • A62 The launchd plist sets PATH=/opt/homebrew/bin:/usr/local/bin:/opt/local/bin:/usr/bin:/bin:/usr/sbin:/sbin: launchd's default PATH lacks Homebrew, so the agent's polls would use osascript although setup tested terminal-notifier. It is fixed rather than copied from the setup shell, so status renders the same plist from any shell. systemd needs nothing: Linux notifiers are distro packages in /usr/bin.
  • A63 shell.txt holds at most 20 reminders plus - … and N more: mokkan list --all, and osc.txt at most 3 (else one N reminders due line), because the prompt hook reads the file on every prompt. A poll whose pending answer arrives after a logout writes no reminder text.
  • A64 Claude runs mokkan through a tool the mod registers at session.start ($.tool.register, mcp__mokkan__mokkan, isDeferred: true), answered by its own tool.call hook, instead of the skill's ! line (A39, A46 for the plugin; /mokkan-cli keeps its ! line). The input is { command, args[] } and reaches the CLI as --exit-zero <command> <args…>, with --exit-zero first so that a -- in the arguments cannot turn it into text. The hook refuses everything outside list push in edit ack done undone pending pop dequeue status balance notify (and notify other than status test doctor on off), so the guard rails no longer depend on the model reading the description. The hook answers before next, so no permission prompt is shown, as with the old pre-approved ! line.
  • A65 prompt.autocomplete offers /mokkan verbs and, for edit, ack, done and undone, rows from the view atom (open rows; Archived for undone), matched by id prefix or text substring, at most 8, written as the full id. It answers only the word right after the verb, since edit <id> takes one id and the rest is text.
  • A66 The Bash guard (tool.call on Bash) matches mokkan, a path ending in /mokkan, or mokkan-cli[@version], then any flags, then accept or delete-account, and denies with the tool's own refusal. It is a backstop to the skills' instructions, not a sandbox: a command line built some other way (a variable, node scripts/mokkan.mjs, an alias) is not caught. Text that merely contains the words (mokkan push "accept the offer") goes through.
  • A67 The pane uses Text's weight (semibold where it drew bold; regular on unselected rows) and so needs Claude Code 2.1.299, the first release after 2.1.296 and the first whose ui.render accepts weight: 2.1.296 refuses the tree (Text prop "weight" is not allowed) and draws no pane. Checked by running the plugin's tests on 2.1.296 and 2.1.299.