ticketlens 0.16.1 → 0.18.0

package/README.md

@@ -394,10 +394,14 @@ Save short notes to yourself — gotchas, context, decisions — and they're aut
 
 The note body is read from stdin, not a flag — this avoids shell-quoting issues with multi-line text. A note can be tied to one ticket (`--ticket=KEY`), or left general (omit `--ticket`) for onboarding-style knowledge that isn't about a specific ticket. Add `--include-attachments` to seed the note with text from that ticket's already-cached attachments (`.txt`/`.md`/`.csv`/`.json` only).
 
-Every note is scanned before saving — anything shaped like a real secret (API key, private key, token) is rejected outright, never silently redacted. Requires a Pro license.
+Every note is scanned before saving — anything shaped like a real secret (API key, private key, token) is rejected outright, never silently redacted. An empty, placeholder (`TODO`, `WIP`, …), or too-short body is rejected the same way. Requires a Pro license.
+
+**Quality loop:** inside a Claude Code session using the jtb skill, a saved note can be silently refined afterward — a generator subagent drafts a more actionable version, a validator subagent checks it against other notes on the same ticket for duplication, up to 3 rounds — and the improved draft overwrites the original via the internal `note patch` command (not typically invoked by hand). This makes zero API calls and costs zero extra tokens beyond your already-running session; it never runs for a bare shell invocation of `note add`, which is skipped silently. Known limitation: a refined draft is not re-synced to your team even if the original was — teammates who already pulled the note keep the earlier draft.
 
 **Team sync:** on a Team plan with Recall enabled for your account (owner-managed, per-tier or per-client), notes also sync to your team's shared pool — `note add` pushes in the background, `recall` pulls the team's notes (cached 4h) before searching. A team manager reviews and verifies incoming notes at `console/admin/recall` before they're marked trusted. Without Team Recall entitlement, everything stays on your machine — no network call.
 
+**Offline resilience:** if a team push fails for a transient reason (network error, timeout, or a 5xx from the backend), the note stays safely in your local vault and is queued for retry — nothing is lost. The queue flushes automatically in the background (at most once every 15 minutes, whenever `recall` or `note add` next talks to the network), or on demand with `ticketlens recall sync`. A session-expired (401) or not-entitled (403) push is never queued — those need you to act (`ticketlens login`, or an owner grant), not a retry. Queued entries expire after 30 days and are capped at 200; switching accounts never flushes a note under the wrong login.
+
 `note add`'s save confirmation and `recall`'s search results are styled by default in a terminal; add `--plain` to either for bare, pipe-safe output. `recall` always shows each note's file ID (e.g. `[1784135399545-fe01c4.md]`) so you can open it directly (`cat ~/.ticketlens/recall/<PREFIX>/<id>`), or pass `--full` to print the full body content inline instead.
 
 **Gaps** — every `ticketlens PROJ-123` brief also diffs the ticket's own description against its linked tickets (from the depth traversal you already requested) and its own downloaded attachments, looking for requirements mentioned there but missing here. Anything uncovered shows up under a `## Gaps` section, citing exactly where it came from — a linked ticket key or an attachment filename — as evidence, never an instruction to act on. Nothing is saved anywhere; it's recomputed fresh on every fetch. Requires a Pro license, same as Recall. No network call beyond what the brief already made.
@@ -672,6 +676,7 @@ ticketlens history <TICKET-KEY>               # Show urgency timeline for a tick
 echo "note body" | ticketlens note add --title="..." --ticket=CNV1-2 --tags=a,b  # Save a note [Pro]
 ticketlens recall CNV1-2                      # Search saved notes by ticket key [Pro]
 ticketlens recall "retry backoff"             # Free-text search across all notes [Pro]
+ticketlens recall sync                        # Retry any notes stuck in the local queue [Pro]
 
 # ── Stats ──────────────────────────────────────────────────────────────────────
 ticketlens stats                              # Response-time metrics from local history
@@ -750,6 +755,7 @@ ticketlens triage --digest               # POST scored triage results to digest
 ticketlens schedule                      # Set up a scheduled daily digest
 ticketlens note add --title="..."        # Save a Recall note (body from stdin)
 ticketlens recall <query|TICKET-KEY>     # Search your saved Recall notes
+ticketlens recall sync                   # Retry any notes stuck in the local queue
 ticketlens activate YOUR-LICENSE-KEY     # Activate Pro license
 ```
 

package/bin/ticketlens.mjs

@@ -610,23 +610,43 @@ switch (command) {
 
   case 'note': {
     if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) { printNoteHelp(); break; }
-    if (cmdArgs[0] !== 'add') {
-      process.stderr.write('Usage: ticketlens note add --title="..." [--ticket=KEY] [--tags=a,b]\n');
-      process.exitCode = 1;
+    if (cmdArgs[0] === 'add') {
+      const { runNoteAdd } = await import('../skills/jtb/scripts/lib/note-command.mjs');
+      runNoteAdd(cmdArgs.slice(1)).then(({ written }) => {
+        if (!written) process.exitCode = 1;
+      }).catch(err => {
+        process.stderr.write(`Error: ${err.message}\n`);
+        process.exitCode = 1;
+      });
       break;
     }
-    const { runNoteAdd } = await import('../skills/jtb/scripts/lib/note-command.mjs');
-    runNoteAdd(cmdArgs.slice(1)).then(({ written }) => {
-      if (!written) process.exitCode = 1;
-    }).catch(err => {
-      process.stderr.write(`Error: ${err.message}\n`);
-      process.exitCode = 1;
-    });
+    if (cmdArgs[0] === 'patch') {
+      const { runNotePatch } = await import('../skills/jtb/scripts/lib/note-command.mjs');
+      runNotePatch(cmdArgs.slice(1)).then(({ patched }) => {
+        if (!patched) process.exitCode = 1;
+      }).catch(err => {
+        process.stderr.write(`Error: ${err.message}\n`);
+        process.exitCode = 1;
+      });
+      break;
+    }
+    process.stderr.write('Usage: ticketlens note add --title="..." [--ticket=KEY] [--tags=a,b]\n');
+    process.exitCode = 1;
     break;
   }
 
   case 'recall': {
     if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) { printRecallHelp(); break; }
+    if (cmdArgs[0] === 'sync') {
+      const { runRecallSync } = await import('../skills/jtb/scripts/lib/recall-command.mjs');
+      runRecallSync(cmdArgs.slice(1)).then(({ ok }) => {
+        if (!ok) process.exitCode = 1;
+      }).catch(err => {
+        process.stderr.write(`Error: ${err.message}\n`);
+        process.exitCode = 1;
+      });
+      break;
+    }
     const { runRecall } = await import('../skills/jtb/scripts/lib/recall-command.mjs');
     runRecall(cmdArgs).then(({ ok }) => {
       if (!ok) process.exitCode = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticketlens",
-  "version": "0.16.1",
+  "version": "0.18.0",
   "description": "Jira CLI for developers — fetch ticket context, triage your queue, and stop tab-switching. Zero dependencies, all local.",
   "type": "module",
   "bin": {

package/skills/jtb/SKILL.md

@@ -1,4 +1,4 @@
-<!-- jtb-skill-version: 0.16.1 -->
+<!-- jtb-skill-version: 0.18.0 -->
 ---
 name: jtb
 description: Fetch a Jira ticket's full context (description, comments, linked issues, code references) and assemble a structured TicketBrief for implementation planning. Use when user types /jtb, mentions a Jira ticket key, or wants to plan work from a Jira ticket.
@@ -53,6 +53,7 @@ Fetches a Jira ticket and produces a structured brief with code references, then
 /jtb cloud-keys timeout anthropic 15   # set per-request timeout in seconds
 /jtb note "gotcha text" --ticket=PROD-1234    # save a Recall note (Pro)
 /jtb recall PROD-1234                  # search saved Recall notes (Pro)
+/jtb recall sync                       # retry any notes stuck in the local queue (Pro)
 ```
 
 ## Prerequisites
@@ -219,8 +220,29 @@ echo "The body text of the note, one or more paragraphs." | \
 
 To search saved notes directly (outside of automatic brief injection): `ticketlens recall "<query>"`.
 
+### Quality loop (Pro, in-session only)
+
+Only when `note add` above was dispatched *by you, inside this skill*, and it printed a saved note id (e.g. `Saved note "Retry gotcha" (1784135399545-fe01c4.md)`) — never for a note a user typed directly into a bare shell, which has no Task/Agent tool available. If there's no such tool in your environment, skip this whole section silently: no warning, no degraded fallback, the note is already saved and that's a complete, correct outcome on its own.
+
+When it does apply, run up to 3 rounds:
+
+1. **Capture the current state** before dispatching anything: get the note file's (`~/.ticketlens/recall/<PREFIX-or-_general>/<id>`) current mtime in epoch **milliseconds** — the shell `stat` command reports seconds on both macOS and Linux, which is the wrong unit and will make every patch silently no-op. Use `node -e "console.log(require('fs').statSync('PATH').mtimeMs)"` instead (Node is already required to run `ticketlens`). Also read the note's current body.
+2. **Generator** — a subagent drafts an improved body: concrete file/line references over vague prose, no invented facts not already established this session.
+3. **Validator** — a separate subagent scores the draft against two criteria: **actionability** (does it read like something a future session could act on directly?) and **non-duplication** (run `ticketlens recall "<query>" --ticket=TICKET-KEY` against the ticket this note is about — reject/rescore a draft that's a near-duplicate of an existing note).
+4. If the draft scores as a genuine improvement, write it back:
+   ```bash
+   echo "The improved body text." | \
+     ticketlens note patch --id="THE-ID-PRINTED-ABOVE" --ticket=TICKET-KEY --expect-mtime="THE-MTIME-FROM-STEP-1"
+   ```
+   `--expect-mtime` is what keeps this safe: if the file changed since step 1 (the user hand-edited it while you were drafting), the patch silently no-ops and prints "not found or already changed" — the user's own edit always wins, never gets clobbered by a stale background draft.
+5. Repeat from step 1 (re-capture mtime/body fresh each round) up to 3 total rounds. If no round ever produces a fully-passing draft, patch in whichever round scored highest across all attempts, and let the "not found or already changed" message stand if that patch itself loses a late race — don't retry past round 3.
+
+This never calls any external API or bills any tokens beyond the session you already have open — the generator and validator are subagents inside your own Claude Code session, not a TicketLens server call.
+
+**Known limitation:** `note patch` only updates the local vault copy. If `note add` already pushed the original draft to a team (Team Recall enabled), a later refinement from this loop is *not* re-pushed — teammates who already pulled the note keep the original draft until this is addressed in a future iteration.
+
 ### Privacy
-Recall notes are stored locally at `~/.ticketlens/recall/`. On a Free/Pro account with no Team Recall entitlement, they never leave the machine — no network calls. On a Team account with Recall enabled (owner-managed, may vary per user), notes also sync to the team's shared pool in the background so teammates can benefit from them too; a team manager reviews and verifies each incoming note before it's marked trusted.
+Recall notes are stored locally at `~/.ticketlens/recall/`. On a Free/Pro account with no Team Recall entitlement, they never leave the machine — no network calls. On a Team account with Recall enabled (owner-managed, may vary per user), notes also sync to the team's shared pool in the background so teammates can benefit from them too; a team manager reviews and verifies each incoming note before it's marked trusted. If a team push fails for a transient reason (network error, timeout, 5xx), the note is queued locally and retried automatically in the background, or on demand with `ticketlens recall sync` — a session-expired or not-entitled push is never queued, since retrying those can't succeed without the user acting first.
 
 ---
 

package/skills/jtb/scripts/lib/help.mjs

@@ -511,6 +511,13 @@ export function printNoteHelp({ stream = process.stdout } = {}) {
     '',
     `    ${s.dim('$')} echo "Retry needs exponential backoff" | ticketlens note add --title="Retry gotcha" --ticket=PROD-123 --tags=bug`,
     '',
+    `  ${s.bold('ticketlens note patch')} ${s.dim('--id="..." [--ticket=KEY]')}  ${s.dim('[Pro]')}`,
+    '',
+    `  Overwrites an existing note's body with a better draft, read from stdin.`,
+    `  Internal mechanism used by the jtb skill's note quality loop inside a Claude`,
+    `  Code session — not typically invoked by hand. Every note it writes gets the`,
+    `  same structural and secret-scan checks ${s.brand('note add')} applies to user input.`,
+    '',
   ];
   stream.write(lines.join('\n') + '\n');
 }
@@ -529,12 +536,17 @@ export function printRecallHelp({ stream = process.stdout } = {}) {
     `    ${s.brand('--full')}        Print each matching note's full body content`,
     `    ${s.brand('-h')}, ${s.brand('--help')}   Show this help`,
     '',
+    `  ${s.bold('COMMANDS')}`,
+    '',
+    `    ${s.brand('sync')}          Manually retry any team-synced notes stuck in the local retry queue ${s.dim('[Pro, requires login]')}`,
+    '',
     `  ${s.bold('EXAMPLES')}`,
     '',
     `    ${s.dim('$')} ticketlens recall PROD-123`,
     `    ${s.dim('$')} ticketlens recall "retry backoff"`,
     `    ${s.dim('$')} ticketlens recall PROD-123 --plain`,
     `    ${s.dim('$')} ticketlens recall PROD-123 --full`,
+    `    ${s.dim('$')} ticketlens recall sync`,
     '',
   ];
   stream.write(lines.join('\n') + '\n');

package/skills/jtb/scripts/lib/note-command.mjs

@@ -10,9 +10,11 @@ import path from 'node:path';
 import { DEFAULT_CONFIG_DIR } from './config.mjs';
 import { isLicensed, showUpgradePrompt } from './license.mjs';
 import { scanForSecrets } from './secret-scanner.mjs';
-import { writeNote } from './recall-vault.mjs';
+import { checkNoteStructure } from './note-structural-check.mjs';
+import { writeNote, patchNoteBody } from './recall-vault.mjs';
 import { readCliToken } from './cli-auth.mjs';
 import { pushNote } from './recall-sync.mjs';
+import { enqueueNote, isRetryableFailure, maybeAutoFlush } from './recall-queue.mjs';
 import { incrementDraftKept, incrementDraftDeleted } from './activity-counter.mjs';
 import { extractText } from './attachment-text.mjs';
 import { TICKET_KEY_PATTERN } from './cli.mjs';
@@ -66,10 +68,14 @@ export async function runNoteAdd(cmdArgs, {
   stream = process.stderr,
   readStdin = defaultReadStdin,
   isLicensedFn = isLicensed,
+  checkNoteStructureFn = checkNoteStructure,
   scanForSecretsFn = scanForSecrets,
   writeNoteFn = writeNote,
   readCliTokenFn = readCliToken,
   pushNoteFn = pushNote,
+  enqueueNoteFn = enqueueNote,
+  isRetryableFailureFn = isRetryableFailure,
+  maybeAutoFlushFn = maybeAutoFlush,
   incrementDraftKeptFn = incrementDraftKept,
   incrementDraftDeletedFn = incrementDraftDeleted,
   listAttachmentsFn = defaultListAttachments,
@@ -103,6 +109,13 @@ export async function runNoteAdd(cmdArgs, {
     body += gatherAttachmentExcerpts(configDir, ticketKey, listAttachmentsFn, extractTextFn);
   }
 
+  const structural = checkNoteStructureFn({ body });
+  if (structural.rejected) {
+    stream.write(`  Note not saved — ${structural.reason}\n`);
+    incrementDraftDeletedFn(configDir);
+    return { written: false };
+  }
+
   const scan = scanForSecretsFn({ title, tags, body });
   if (scan.rejected) {
     stream.write(`  Note not saved — ${scan.reasons.join(' ')}\n`);
@@ -122,13 +135,78 @@ export async function runNoteAdd(cmdArgs, {
 
   const cliToken = readCliTokenFn(configDir);
   if (cliToken) {
+    const warn = (s) => stream.write(s);
     // Field names match PushRequest's validation rules (external_id, tickets) —
     // the backend wire contract, not the local vault's internal camelCase shape.
-    await pushNoteFn(
-      { external_id: id, title, tickets: ticketKeys, tags, author, sources: [], body },
-      { cliToken, configDir, warn: (s) => stream.write(s) },
-    );
+    const payload = { external_id: id, title, tickets: ticketKeys, tags, author, sources: [], body };
+    const result = await pushNoteFn(payload, { cliToken, configDir, warn });
+    if (isRetryableFailureFn(result)) {
+      enqueueNoteFn(payload, { cliToken, configDir, warn });
+    }
+    await maybeAutoFlushFn({ cliToken, configDir });
   }
 
   return { written: true };
 }
+
+/**
+ * Implements `tl note patch` — overwrites an existing note's body with a
+ * better draft. Internal plumbing for the jtb skill's quality loop (never
+ * meant to be typed by hand): the loop's generator subagent produces a body,
+ * SKILL.md's orchestration pipes it through this command, and the new body
+ * gets exactly the same structural and secret gates a user-typed body gets —
+ * there is no weaker path here for AI-authored content.
+ *
+ * @param {string[]} cmdArgs
+ * @returns {Promise<{ patched: boolean }>}
+ */
+export async function runNotePatch(cmdArgs, {
+  configDir = DEFAULT_CONFIG_DIR,
+  stream = process.stderr,
+  readStdin = defaultReadStdin,
+  isLicensedFn = isLicensed,
+  checkNoteStructureFn = checkNoteStructure,
+  scanForSecretsFn = scanForSecrets,
+  patchNoteBodyFn = patchNoteBody,
+} = {}) {
+  if (!isLicensedFn('pro', configDir)) {
+    showUpgradePrompt('pro', 'ticketlens note', { stream });
+    return { patched: false };
+  }
+
+  const id = parseFlag(cmdArgs, 'id');
+  if (!id) {
+    stream.write('Usage: ticketlens note patch --id="..." [--ticket=KEY]\n');
+    return { patched: false };
+  }
+
+  const ticketKey = parseFlag(cmdArgs, 'ticket');
+  if (ticketKey && !TICKET_KEY_PATTERN.test(ticketKey)) {
+    stream.write(`  Invalid --ticket value "${ticketKey}" — expected a ticket key like PROJ-123.\n`);
+    return { patched: false };
+  }
+
+  const body = await readStdin();
+
+  const structural = checkNoteStructureFn({ body });
+  if (structural.rejected) {
+    stream.write(`  Note not updated — ${structural.reason}\n`);
+    return { patched: false };
+  }
+
+  const scan = scanForSecretsFn({ title: '', tags: [], body });
+  if (scan.rejected) {
+    stream.write(`  Note not updated — ${scan.reasons.join(' ')}\n`);
+    return { patched: false };
+  }
+  for (const warning of scan.warnings) {
+    stream.write(`  Warning: ${warning}\n`);
+  }
+
+  const ticketKeys = ticketKey ? [ticketKey] : [];
+  const expectMtimeArg = parseFlag(cmdArgs, 'expect-mtime');
+  const expectedMtimeMs = expectMtimeArg !== undefined ? Number(expectMtimeArg) : undefined;
+  const { patched } = patchNoteBodyFn({ id, ticketKeys, body, expectedMtimeMs }, { configDir });
+  stream.write(patched ? `  Updated note (${id})\n` : `  Note not updated — (${id}) not found or already changed.\n`);
+  return { patched };
+}

package/skills/jtb/scripts/lib/note-structural-check.mjs

@@ -0,0 +1,33 @@
+/**
+ * Deterministic, dependency-free structural gate for a Recall note's body —
+ * catches empty, placeholder, or too-thin content before it's ever written
+ * to the vault. Separate concern from secret-scanner.mjs: this never judges
+ * sensitivity, only whether there's real content here at all.
+ */
+
+const MIN_BODY_LENGTH = 10;
+
+const PLACEHOLDER_BODIES = new Set([
+  'todo', 'test', 'n/a', 'na', 'tbd', 'wip', 'placeholder',
+  'xxx', 'asdf', 'fixme', 'fix me', '.', '-',
+]);
+
+/**
+ * @param {{ body?: string }} note
+ * @returns {{ rejected: boolean, reason: string|null }}
+ */
+export function checkNoteStructure({ body = '' } = {}) {
+  const trimmed = body.trim();
+
+  if (trimmed.length === 0) {
+    return { rejected: true, reason: 'Note body is empty.' };
+  }
+  if (PLACEHOLDER_BODIES.has(trimmed.toLowerCase())) {
+    return { rejected: true, reason: `Note body "${trimmed}" looks like a placeholder, not real content.` };
+  }
+  if (trimmed.length < MIN_BODY_LENGTH) {
+    return { rejected: true, reason: `Note body is too short to be useful (minimum ${MIN_BODY_LENGTH} characters).` };
+  }
+
+  return { rejected: false, reason: null };
+}

package/skills/jtb/scripts/lib/recall-command.mjs

@@ -12,6 +12,7 @@ import { isLicensed, showUpgradePrompt } from './license.mjs';
 import { listNotes } from './recall-vault.mjs';
 import { readCliToken } from './cli-auth.mjs';
 import { pullNotes } from './recall-sync.mjs';
+import { maybeAutoFlush, flushQueue, readQueue } from './recall-queue.mjs';
 import { styleRecallResults } from './styled-assembler.mjs';
 
 /**
@@ -26,6 +27,7 @@ export async function runRecall(cmdArgs, {
   listNotesFn = listNotes,
   readCliTokenFn = readCliToken,
   pullNotesFn = pullNotes,
+  maybeAutoFlushFn = maybeAutoFlush,
 } = {}) {
   if (!isLicensedFn('pro', configDir)) {
     showUpgradePrompt('pro', 'ticketlens recall', { stream: errorStream });
@@ -45,6 +47,7 @@ export async function runRecall(cmdArgs, {
       configDir,
       ...(cmdArgs.includes('--no-cache') && { ttlMs: 0 }),
     });
+    await maybeAutoFlushFn({ cliToken, configDir });
   }
 
   const filter = TICKET_KEY_PATTERN.test(arg) ? { ticketKey: arg } : { query: arg };
@@ -55,3 +58,41 @@ export async function runRecall(cmdArgs, {
   stream.write(styleRecallResults(results, { styled, full }) + '\n');
   return { ok: true };
 }
+
+/**
+ * Implements `tl recall sync` — manually flushes the local retry queue
+ * (notes whose team push previously failed for a transient reason). Unlike
+ * the auto-flush attempted from `runRecall`/`note add`, this is an explicit
+ * user action, so failures are reported visibly rather than staying silent.
+ *
+ * @param {string[]} cmdArgs
+ * @returns {Promise<{ ok: boolean }>}
+ */
+export async function runRecallSync(cmdArgs, {
+  configDir = DEFAULT_CONFIG_DIR,
+  stream = process.stdout,
+  isLicensedFn = isLicensed,
+  readCliTokenFn = readCliToken,
+  readQueueFn = readQueue,
+  flushQueueFn = flushQueue,
+} = {}) {
+  if (!isLicensedFn('pro', configDir)) {
+    showUpgradePrompt('pro', 'ticketlens recall', { stream });
+    return { ok: false };
+  }
+
+  const cliToken = readCliTokenFn(configDir);
+  if (!cliToken) {
+    stream.write('Not logged in — run `ticketlens login` first.\n');
+    return { ok: false };
+  }
+
+  if (readQueueFn(configDir).length === 0) {
+    stream.write('Nothing to sync.\n');
+    return { ok: true };
+  }
+
+  const { flushed, remaining } = await flushQueueFn({ cliToken, configDir, warn: (s) => stream.write(s) });
+  stream.write(`Synced ${flushed} note(s). ${remaining} still pending.\n`);
+  return { ok: true };
+}

package/skills/jtb/scripts/lib/recall-queue.mjs

@@ -0,0 +1,227 @@
+/**
+ * Local retry queue for Recall notes whose push to the team backend failed
+ * for a transient reason (network error, timeout, or 5xx). A note is never
+ * lost — it's already safe in the local vault (recall-vault.mjs) before this
+ * module ever sees it; this only tracks the separate, best-effort intent to
+ * also sync it to the team.
+ *
+ * Retry classification happens once, at the moment the original push fails
+ * (isRetryableFailure) — 401/403/other-4xx are deliberately excluded: a
+ * stale session or a doomed payload will never succeed by retrying, and
+ * pushNote already warns the user about those synchronously.
+ *
+ * Growth is bounded two independent ways: a hard cap on entry count, and an
+ * age-based expiry keyed off firstQueuedAt (not failedAt, which refreshes on
+ * every retry attempt and would otherwise let a perpetually-failing entry
+ * live forever).
+ *
+ * enqueueNote/flushQueue do read-modify-write on the queue file with no file
+ * lock — same tradeoff already accepted by recall-pull-state.json and
+ * recall-entitlement-state.json in recall-sync.mjs. Two concurrent CLI
+ * invocations racing this file can lose one writer's update. Bounded,
+ * accepted risk: this queue is a retry-intent cache, not the source of truth
+ * (the note itself is already safe in the vault before it ever reaches here)
+ * — not worth a lock for a low-frequency, single-user CLI tool.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { DEFAULT_CONFIG_DIR } from './config.mjs';
+import { writeFileAtomically } from './recall-vault.mjs';
+import { pushNote, hashToken } from './recall-sync.mjs';
+
+const QUEUE_FILE = 'recall-pending.json';
+const FLUSH_STATE_FILE = 'recall-flush-state.json';
+
+export const MAX_QUEUE_SIZE = 200;
+export const MAX_ENTRY_AGE_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+export const AUTO_FLUSH_INTERVAL_MS = 15 * 60 * 1000; // 15 minutes
+
+function queuePath(configDir) {
+  return path.join(configDir, QUEUE_FILE);
+}
+
+function flushStatePath(configDir) {
+  return path.join(configDir, FLUSH_STATE_FILE);
+}
+
+/**
+ * @param {string} configDir
+ * @returns {Array<{id: string, notePayload: object, tokenHash: string, firstQueuedAt: string, failedAt: string, attempts: number}>}
+ */
+export function readQueue(configDir) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(queuePath(configDir), 'utf8'));
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+function writeQueue(configDir, entries) {
+  writeFileAtomically(queuePath(configDir), JSON.stringify(entries));
+}
+
+function purgeExpired(entries, now) {
+  return entries.filter(entry => now - new Date(entry.firstQueuedAt).getTime() <= MAX_ENTRY_AGE_MS);
+}
+
+/**
+ * Decides whether a failed push is worth retrying later. Network errors and
+ * timeouts (pushNote returns no `status` for these) and 5xx responses are
+ * transient. 401 (session expired), 403 (not entitled / no team), and any
+ * other 4xx (e.g. a validation failure) are not — retrying cannot fix them
+ * without the user acting, or would just retry a payload that will never be
+ * accepted.
+ *
+ * @param {{ ok: boolean, status?: number }} result
+ * @returns {boolean}
+ */
+export function isRetryableFailure(result) {
+  return !result.ok && (result.status === undefined || result.status >= 500);
+}
+
+/**
+ * Queues a note for later retry after a transient push failure. Purges
+ * expired entries first, then evicts the oldest entry (with a single warn)
+ * if appending would exceed MAX_QUEUE_SIZE.
+ *
+ * @param {object}   notePayload - exact wire payload passed to pushNote
+ * @param {object}   opts
+ * @param {string}   opts.cliToken
+ * @param {string}   [opts.configDir]
+ * @param {() => number} [opts.now]
+ * @param {Function} [opts.warn]
+ */
+export function enqueueNote(notePayload, {
+  cliToken,
+  configDir = DEFAULT_CONFIG_DIR,
+  now = () => Date.now(),
+  warn = (s) => process.stderr.write(s),
+} = {}) {
+  const nowMs = now();
+  let entries = purgeExpired(readQueue(configDir), nowMs);
+
+  if (entries.length >= MAX_QUEUE_SIZE) {
+    entries = entries.slice(1);
+    warn('  Recall queue full — dropped the oldest queued note to make room.\n');
+  }
+
+  const nowIso = new Date(nowMs).toISOString();
+  entries.push({
+    id: notePayload.external_id,
+    notePayload,
+    tokenHash: hashToken(cliToken),
+    firstQueuedAt: nowIso,
+    failedAt: nowIso,
+    attempts: 0,
+  });
+
+  writeQueue(configDir, entries);
+}
+
+/**
+ * Attempts to push every queued entry belonging to the current account
+ * (matched by tokenHash). Entries queued under a different account are left
+ * untouched — never attempted, never evicted by this pass. Expired entries
+ * are purged first, regardless of tokenHash.
+ *
+ * @param {object}   opts
+ * @param {string}   opts.cliToken
+ * @param {string}   [opts.configDir]
+ * @param {Function} [opts.pushNoteFn]
+ * @param {Function} [opts.warn] - defaults to silent; callers doing a visible/manual sync should pass a real one
+ * @param {() => number} [opts.now]
+ * @returns {Promise<{ flushed: number, remaining: number }>}
+ */
+export async function flushQueue({
+  cliToken,
+  configDir = DEFAULT_CONFIG_DIR,
+  pushNoteFn = pushNote,
+  isRetryableFailureFn = isRetryableFailure,
+  warn = () => {},
+  now = () => Date.now(),
+} = {}) {
+  const nowMs = now();
+  const currentHash = hashToken(cliToken);
+  const entries = purgeExpired(readQueue(configDir), nowMs);
+
+  let flushed = 0;
+  const remaining = [];
+  for (const entry of entries) {
+    if (entry.tokenHash !== currentHash) {
+      remaining.push(entry);
+      continue;
+    }
+
+    const result = await pushNoteFn(entry.notePayload, { cliToken, configDir, warn });
+    if (result.ok) {
+      flushed++;
+      continue;
+    }
+
+    // A retry can surface a DIFFERENT failure than the one that originally
+    // queued this entry (e.g. the session expired between enqueue and this
+    // attempt) — reclassify every time rather than trusting the original
+    // enqueue decision, so a now-unrecoverable entry is dropped immediately
+    // instead of silently retrying for up to MAX_ENTRY_AGE_MS.
+    if (!isRetryableFailureFn(result)) continue;
+
+    remaining.push({ ...entry, attempts: entry.attempts + 1, failedAt: new Date(nowMs).toISOString() });
+  }
+
+  writeQueue(configDir, remaining);
+  return { flushed, remaining: remaining.length };
+}
+
+function readLastFlushAttemptAt(configDir) {
+  try {
+    return JSON.parse(fs.readFileSync(flushStatePath(configDir), 'utf8')).lastAttemptAt ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function writeLastFlushAttemptAt(configDir, isoTimestamp) {
+  try {
+    fs.writeFileSync(flushStatePath(configDir), JSON.stringify({ lastAttemptAt: isoTimestamp }), 'utf8');
+  } catch {
+    // Non-fatal — worst case the next command re-checks a moment sooner than the interval intends.
+  }
+}
+
+/**
+ * Time-gated background flush, attempted from the CLI's existing
+ * Recall-touching entry points (note add's push, recall's pull) rather than
+ * on every invocation — a no-op unless the queue is non-empty AND at least
+ * AUTO_FLUSH_INTERVAL_MS has passed since the last attempt. The attempt
+ * timestamp is recorded even on failure, so a down backend can't be hammered
+ * once per command within the window.
+ *
+ * @param {object}   opts
+ * @param {string}   opts.cliToken
+ * @param {string}   [opts.configDir]
+ * @param {() => number} [opts.now]
+ * @param {Function} [opts.flushQueueFn]
+ */
+export async function maybeAutoFlush({
+  cliToken,
+  configDir = DEFAULT_CONFIG_DIR,
+  now = () => Date.now(),
+  flushQueueFn = flushQueue,
+} = {}) {
+  if (readQueue(configDir).length === 0) return;
+
+  const lastAttemptAt = readLastFlushAttemptAt(configDir);
+  const nowMs = now();
+  if (lastAttemptAt && nowMs - new Date(lastAttemptAt).getTime() < AUTO_FLUSH_INTERVAL_MS) return;
+
+  try {
+    await flushQueueFn({ cliToken, configDir, now });
+  } catch {
+    // A down backend or a thrown network error must never crash the command
+    // that opportunistically triggered this background attempt.
+  } finally {
+    writeLastFlushAttemptAt(configDir, new Date(nowMs).toISOString());
+  }
+}

package/skills/jtb/scripts/lib/recall-sync.mjs

@@ -56,7 +56,7 @@ function entitlementCachePath(configDir) {
 // switch (e.g. login as someone else) so a stale cache never suppresses a
 // different account's push. Found via Local Live Test: configDir alone is
 // not a valid cache key — cli-token.json can change without configDir changing.
-function hashToken(cliToken) {
+export function hashToken(cliToken) {
   return createHash('sha256').update(cliToken).digest('hex');
 }
 
@@ -107,7 +107,11 @@ export async function pushNote(note, {
   // flips the Recall grant — without this, the warning below repeats forever.
   const checkedAt = readEntitlementCheckedAt(configDir, cliToken);
   if (checkedAt && now() - new Date(checkedAt).getTime() < ttlMs) {
-    return { ok: false, skipped: true };
+    // status: 403 — this is a cached replay of the entitlement 403 below, not a
+    // fresh network outcome. Without it, isRetryableFailure's "no status means
+    // network error" rule misclassifies this as transient and queues a note
+    // that can never succeed until the owner grants entitlement.
+    return { ok: false, status: 403, skipped: true };
   }
 
   warnIfInsecure(apiBase(), warn);

package/skills/jtb/scripts/lib/recall-vault.mjs

@@ -49,7 +49,7 @@ function generateNoteId() {
   return `${Date.now()}-${randomBytes(3).toString('hex')}.md`;
 }
 
-function writeFileAtomically(filePath, contents) {
+export function writeFileAtomically(filePath, contents) {
   const tmpPath = `${filePath}.${process.pid}.tmp`;
   fs.writeFileSync(tmpPath, contents, 'utf8');
   fs.renameSync(tmpPath, filePath);
@@ -164,6 +164,59 @@ export function deleteNote({ external_id: externalId, tickets = [] }, { configDi
   return { deleted: true, prefix };
 }
 
+/**
+ * Overwrites an existing local note's body in place — used by the jtb skill's
+ * generator/validator quality loop to swap in a better draft after `note add`
+ * already saved the original. Patch-only: never creates a note, and every
+ * frontmatter field except body is carried over unchanged, so this can never
+ * become a covert way to retitle/retag/re-tie a note to a different ticket.
+ *
+ * Guards, same failure-mode split as deleteNote: a malformed id or ticket key
+ * is a caller bug (throw); a missing file, an externalId that doesn't match
+ * what's on disk, or a body that changed since the caller last observed it
+ * (expectedMtimeMs) are all best-effort no-ops, not errors — the original
+ * note is always left exactly as-is on any of these.
+ *
+ * @param {{ id: string, ticketKeys?: string[], body: string, expectedMtimeMs?: number }} params
+ * @param {{ configDir?: string }} [opts]
+ * @returns {{ patched: boolean, path: string|null }}
+ */
+export function patchNoteBody({ id, ticketKeys = [], body, expectedMtimeMs }, { configDir = DEFAULT_CONFIG_DIR } = {}) {
+  if (!EXTERNAL_ID_PATTERN.test(id)) {
+    throw new Error(`Invalid note id: "${id}"`);
+  }
+
+  const prefix = resolvePrefix(ticketKeys[0]);
+  const notePath = path.join(prefixDir(configDir, prefix), id);
+
+  if (!fs.existsSync(notePath)) {
+    return { patched: false, path: null };
+  }
+  if (expectedMtimeMs !== undefined && fs.statSync(notePath).mtimeMs !== expectedMtimeMs) {
+    return { patched: false, path: notePath };
+  }
+
+  const existing = readNote(notePath);
+  if (!existing || existing.externalId !== id) {
+    return { patched: false, path: notePath };
+  }
+
+  const data = {
+    title: existing.title,
+    aliases: existing.aliases,
+    tickets: existing.tickets,
+    tags: existing.tags,
+    author: existing.author,
+    created: existing.created,
+    status: existing.status,
+    sources: existing.sources,
+    externalId: existing.externalId,
+  };
+
+  writeFileAtomically(notePath, serializeFrontmatter(data, body));
+  return { patched: true, path: notePath };
+}
+
 /**
  * Reads one note file. Never trusts the file completely — a note can be
  * hand-edited (README documents them as plain markdown, readable in any