ticketlens 0.38.56 → 0.39.0

package/README.md

@@ -462,7 +462,7 @@ Every note is scanned before saving — anything shaped like a real secret (API
 
 **Removing a note:** `ticketlens note delete --id="..." [--ticket=KEY]` removes a note from your local vault. Local only — if it was already pushed to a team, teammates who pulled it keep their copy; deleting it there too is a manager action from the Console (Admin > Recall).
 
-**Any MCP-capable AI harness:** `ticketlens mcp` starts a stdio [MCP](https://modelcontextprotocol.io) server exposing `fetch`, `triage`, `compliance`, `review`, `standup`, `pr`, `stats`, `issue_types`, `history`, `collisions`, `ledger`, `doctor`, `recall_add`, `recall_update`, `recall_delete`, `recall_search`, `ticket_comment`, `ticket_transition`, `ticket_assign`, `ticket_duplicates`, `ticket_link`, `ticket_update`, and `ticket_create` as native tools — every CLI action now has an MCP tool, so any MCP-compatible AI assistant, not just Claude Code, can call them directly instead of constructing a shell command. It's a thin adapter over the exact same code as the CLI commands above — same license gate per tool, same secret scan/local vault/tracker writes, same team sync — nothing is reimplemented. `fetch`, `doctor`, and `standup` are Free; `triage`'s base scan is Free with some options gated Pro/Team, same as the CLI (`ticketlens triage --help`); `compliance` and `pr` are Free, sharing a 3-checks/month cap on their requirements-coverage section, Pro unlimited; `compliance` additionally accepts `consensus: true` (Pro) to replace the local deterministic matcher with a multi-agent AI review, run server-side against a "consensus" role configured at Console > Admin > AI Roles (2+ providers from the team's shared pool), and always implies `--yes` under MCP since there's no TTY for the cost-confirmation prompt; `review` is Free for branch/files/ticket context, with its coverage/focus section requiring Pro as a plain license check — it does not draw from that same monthly counter; `stats` is Free with a 7-day lookback cap, Pro extends it to 30 days, same split as the CLI (`ticketlens stats --help`); `issue_types` is Free and Jira-only — pre-fetches and caches a profile's real creatable projects and issue types ahead of a `ticket_create` attempt, sharing its cache with that tool's own reactive enrichment; accepts an optional `project` to skip the full scan and return just that one project's types (3-day cache, vs. 7-day for the full scan); Linear/GitHub profiles get a clear "not available" instead of an empty result; `history` reads local triage history only (zero network) and requires Pro; `collisions` requires `ticketlens login` (Console access) plus a Team license; `ledger` exports the local, signed compliance audit trail (zero network) and requires Pro; every other tool needs Pro. `recall_update` overwrites an existing Recall note's body — internal plumbing for the note quality loop, not typically called directly; its `attachments` array appends new files to whatever the note already has, same as `recall_add`'s, never replacing existing ones. `recall_delete` is destructive and local-vault-only — requires `confirm: true` alongside `id` to actually execute; there is no interactive y/N prompt under MCP (no real terminal to prompt against), so omitting it always fails rather than silently blocking. Point your harness's MCP config at it: `{ "command": "ticketlens", "args": ["mcp"] }` — or run `ticketlens mcp install` in a project to write that entry into its `.mcp.json` for you (creates the file if it doesn't exist, merges in if it does — never touches any other entry already there; `--dry-run` to preview first).
+**Any MCP-capable AI harness:** `ticketlens mcp` starts a stdio [MCP](https://modelcontextprotocol.io) server exposing `fetch`, `triage`, `compliance`, `review`, `standup`, `pr`, `stats`, `issue_types`, `history`, `collisions`, `ledger`, `doctor`, `recall_add`, `recall_update`, `recall_delete`, `recall_search`, `ticket_comment`, `ticket_transition`, `ticket_assign`, `ticket_duplicates`, `ticket_link`, `ticket_update`, `ticket_create`, and `ticket_worklog` as native tools — every CLI action now has an MCP tool, so any MCP-compatible AI assistant, not just Claude Code, can call them directly instead of constructing a shell command. It's a thin adapter over the exact same code as the CLI commands above — same license gate per tool, same secret scan/local vault/tracker writes, same team sync — nothing is reimplemented. `fetch`, `doctor`, and `standup` are Free; `triage`'s base scan is Free with some options gated Pro/Team, same as the CLI (`ticketlens triage --help`); `compliance` and `pr` are Free, sharing a 3-checks/month cap on their requirements-coverage section, Pro unlimited; `compliance` additionally accepts `consensus: true` (Pro) to replace the local deterministic matcher with a multi-agent AI review, run server-side against a "consensus" role configured at Console > Admin > AI Roles (2+ providers from the team's shared pool), and always implies `--yes` under MCP since there's no TTY for the cost-confirmation prompt; `review` is Free for branch/files/ticket context, with its coverage/focus section requiring Pro as a plain license check — it does not draw from that same monthly counter; `stats` is Free with a 7-day lookback cap, Pro extends it to 30 days, same split as the CLI (`ticketlens stats --help`); `issue_types` is Free and Jira-only — pre-fetches and caches a profile's real creatable projects and issue types ahead of a `ticket_create` attempt, sharing its cache with that tool's own reactive enrichment; accepts an optional `project` to skip the full scan and return just that one project's types (3-day cache, vs. 7-day for the full scan); Linear/GitHub profiles get a clear "not available" instead of an empty result; `history` reads local triage history only (zero network) and requires Pro; `collisions` requires `ticketlens login` (Console access) plus a Team license; `ledger` exports the local, signed compliance audit trail (zero network) and requires Pro; every other tool needs Pro. `recall_update` overwrites an existing Recall note's body — internal plumbing for the note quality loop, not typically called directly; its `attachments` array appends new files to whatever the note already has, same as `recall_add`'s, never replacing existing ones. `recall_delete` is destructive and local-vault-only — requires `confirm: true` alongside `id` to actually execute; there is no interactive y/N prompt under MCP (no real terminal to prompt against), so omitting it always fails rather than silently blocking. Point your harness's MCP config at it: `{ "command": "ticketlens", "args": ["mcp"] }` — or run `ticketlens mcp install` in a project to write that entry into its `.mcp.json` for you (creates the file if it doesn't exist, merges in if it does — never touches any other entry already there; `--dry-run` to preview first).
 
 `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. Each result shows a relative time (`2h ago`, `3d ago`) rather than a bare date — the full-precision timestamp is always in the note file's own frontmatter.
 
@@ -490,14 +490,18 @@ ticketlens update PROJ-123 --add-labels=urgent,backend --remove-labels=stale
 ticketlens create --project=PROJ --type="Task" --summary="Fix login on mobile"  # Create a new ticket
 ticketlens create --project=ENG --summary="New Linear issue" --profile=linear-team
 ticketlens create --project=PROJ --type="Bug" --summary="Broken layout" --attach=./screenshot.png
+ticketlens worklog PROJ-123=1h30m                            # Preview a worklog — writes nothing (Jira only)
+ticketlens worklog PROJ-123=1h30m PROJ-456=45m --comment="Sprint work" --confirm  # Log time on several tickets
 ```
 
-Write directly to the ticket in its real tracker — Jira, GitHub, or Linear — from your terminal or an AI session via `ticket_comment`/`ticket_transition`/`ticket_assign`/`ticket_duplicates`/`ticket_link`/`ticket_update`/`ticket_create` MCP tools. Requires a Pro license.
+Write directly to the ticket in its real tracker — Jira, GitHub, or Linear — from your terminal or an AI session via `ticket_comment`/`ticket_transition`/`ticket_assign`/`ticket_duplicates`/`ticket_link`/`ticket_update`/`ticket_create`/`ticket_worklog` MCP tools. Requires a Pro license.
 
 `ticketlens transition` with just a ticket key lists the tracker's current valid options without changing anything (Jira: real workflow transitions for that issue; GitHub: open/closed; Linear: team-scoped workflow states). Add both `--target` and `--confirm` to execute — `--confirm` is a deliberate two-step gate: a behavioral nudge and forensic trail, not a hard security guarantee. Every write, once resolved, is re-validated against the tracker's current state immediately before executing — never a blind write against a stale option.
 
 `ticketlens assign` is self-assign only for now — `--to` must be `me`. Assigning to someone else needs a per-tracker user-lookup step this doesn't do yet, so it's deliberately out of scope until that's built.
 
+`ticketlens worklog` logs time on one or several **Jira** tickets, always as you — GitHub and Linear have no worklog API and are refused. Durations are hours and minutes only (`2h`, `90m`, `1h30m`, up to 24h each; days and weeks are rejected because Jira defines them per instance). Every entry's format and tracker are checked before any is written (Jira-side failures like an unknown ticket are reported per ticket, naming what already landed so a retry never repeats it), and since a worklog can't be deleted through TicketLens, nothing is written without `--confirm` — without it you get a preview. `--started=` takes ISO 8601 with a time (default now; not in the future, not older than a year). One call logs at most 24h in total, and a write that times out holds that ticket for 10 minutes because it may have landed. The `ticket_worklog` MCP tool takes an `entries` array with a per-ticket `comment`/`started`; the CLI applies one `--comment`/`--started` to every ticket.
+
 `ticketlens duplicates` is read-only — it never links or changes anything, just lists likely matches in the same project. No tracker (Jira/GitHub/Linear) scores similarity server-side, so ranking happens locally from title/description word overlap; treat a match as a nudge to check manually, not a verdict. That local scoring can also miss a real duplicate — an empty result means none were found by this heuristic, not a confirmed absence. `--threshold=N` (0–1, default 0.35) controls how loose a match counts.
 
 `ticketlens link SOURCE-KEY TARGET-KEY` links two tickets — direction matters: SOURCE "types" TARGET (e.g. `link A B --type=Duplicate` means A duplicates B, not the other way around). With just the two keys it lists the tracker's current valid link types without changing anything — always fetched live for Jira, since link type names are per-instance configurable there. GitHub is different from Jira/Linear: it has no generic link relationship, so linking on a GitHub-tracked ticket *closes SOURCE as a duplicate of TARGET* — a state change, not just a relationship add — and prints an explicit warning immediately before that happens, on top of the same `--confirm` gate.
@@ -837,6 +841,8 @@ ticketlens update CNV1-2 --add-labels=urgent --remove-labels=stale  # Add/remove
 ticketlens create --project=CNV1 --type="Task" --summary="New ticket"  # Create a new ticket [Pro]
 ticketlens create --project=ENG --summary="New issue" --profile=linear-team  # Create on a different profile [Pro]
 ticketlens create --project=CNV1 --type="Bug" --summary="Broken layout" --attach=./screenshot.png  # Create with an attachment [Pro]
+ticketlens worklog CNV1-2=1h30m                             # Preview a worklog — writes nothing (Jira only) [Pro]
+ticketlens worklog CNV1-2=1h30m CNV1-3=45m --confirm        # Log time on several tickets (Jira only) [Pro]
 
 # ── Stats ──────────────────────────────────────────────────────────────────────
 ticketlens stats                              # Response-time metrics from local history
@@ -940,6 +946,7 @@ ticketlens duplicates CNV1-2             # Find likely duplicates (read-only)
 ticketlens link CNV1-2 CNV1-3 --type="Duplicate" --confirm  # Link two tickets
 ticketlens update CNV1-2 --title="..."   # Update title/description/labels/priority
 ticketlens create --project=CNV1 --type="Task" --summary="..."  # Create a new ticket
+ticketlens worklog CNV1-2=1h30m --confirm  # Log time on a Jira ticket
 ticketlens activate YOUR-LICENSE-KEY     # Activate Pro license
 ```
 
@@ -1099,14 +1106,18 @@ npm test
 See [ROADMAP.md](ROADMAP.md) for the full plan.
 
 Recently shipped:
-- **Prefix & status pickers** (`ticketlens init` / `config`, v0.12.0) — ticket prefixes and triage statuses are picked from your Jira instance's live project/status lists via multi-select; editing pre-selects current values, unchecking removes them, and stale entries are flagged `(not on server)`
-- **Collision detection** (`ticketlens collisions`) — shows which files your branch shares with teammates' in-flight branches; `--push` auto-sends git branch data to the team snapshot. Team tier
-- **Shareable triage snapshot** (`ticketlens triage --share`) — generates a 24h signed URL; recipients open it in any browser, no account needed. Team tier
-- **Compliance push** (`ticketlens triage --push`) — enriches the team snapshot with per-ticket compliance status and coverage from the local ledger. Pro tier
-- **"TicketLens for PRs"** (`ticketlens review`) — assembles a code-review context brief from your current branch: linked tickets, changed files, and ticket context in one brief
-- **Confluence pages** — linked Confluence pages fetched automatically and included in the brief; origin-validated, non-fatal, capped at 10 pages
-- **Linear support** — `ticketlens init` → Linear; connects via GraphQL API key, fetches tickets, triage, and statuses
-- **GitHub Issues support** — `ticketlens init` → GitHub Issues; PAT-based, same normalized ticket shape
+- **Worklog** (`ticketlens worklog KEY=DURATION ... --confirm` / `ticket_worklog` MCP tool) — log time on one or several Jira tickets, preview-first, all entries validated before any is written. Pro tier
+- **Autonomous Recall capture** — TicketLens judges and saves a note after a session, no `note add` call, reusing your login. Pro+ tier
+- **Multi-agent AI consensus compliance** (`ticketlens compliance TICKET --consensus`) — routes requirements-vs-diff review through your team's AI provider pool, majority vote after a refinement round. Pro tier
+- **Dynamic AI Provider Registry** (Console > Admin > AI Provider Pool / AI Roles) — manage arbitrary AI providers and role-based routing, no fixed vendor list
+- **Full MCP tool coverage** (`ticketlens mcp`) — every CLI action (fetch, triage, compliance, recall, ticket writes) has a matching MCP tool
+- **`ticketlens issue-types`** — pre-fetches and caches a project's valid issue types, speeds up `ticket_create`
+- **Recall team sync** (`note add` / `recall`) — shared notes with Console verification, attachments, configurable capture strictness. Pro/Team tier
+- **`ticketlens doctor`** — diagnoses profile/connection/license/MCP problems; `--fix` for common issues
+- **Ticket write-back** (`comment`/`transition`/`assign`/`duplicates`/`link`/`update`/`create`) — write directly to Jira/GitHub/Linear from the CLI. Pro tier
+- **Stale status detection** — flags tickets stuck in a status too long, team-configurable thresholds. Pro tier
+- **Shared team Jira config** (Console > Admin > Jira) — manager sets the connection once, team inherits it. Pro+ tier
+- **Slack/Teams alerts** — needs-response, aging, and compliance-gap alerts plus a weekly digest. Team tier
 
 ---
 

package/bin/ticketlens.mjs

@@ -30,7 +30,7 @@ import {
   printCollisionsHelp, printStatsHelp, printIssueTypesHelp, printDoctorHelp,
   printCloudKeysHelp,
   printNoteHelp, printRecallHelp, printMcpHelp,
-  printCommentHelp, printTransitionHelp, printAssignHelp, printDuplicatesHelp, printLinkHelp, printUpdateHelp, printCreateHelp,
+  printCommentHelp, printTransitionHelp, printAssignHelp, printWorklogHelp, printDuplicatesHelp, printLinkHelp, printUpdateHelp, printCreateHelp,
 } from '../skills/jtb/scripts/lib/help.mjs';
 import { runStats } from '../skills/jtb/scripts/lib/run-stats.mjs';
 import { runIssueTypes } from '../skills/jtb/scripts/lib/run-issue-types.mjs';
@@ -835,6 +835,18 @@ switch (command) {
     break;
   }
 
+  case 'worklog': {
+    if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) { printWorklogHelp(); break; }
+    const { runTicketWorklog } = await import('../skills/jtb/scripts/lib/ticket-worklog.mjs');
+    runTicketWorklog(cmdArgs).then(({ ok }) => {
+      if (!ok) process.exitCode = 1;
+    }).catch(err => {
+      process.stderr.write(`Error: ${err.message}\n`);
+      process.exitCode = 1;
+    });
+    break;
+  }
+
   case 'duplicates': {
     if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) { printDuplicatesHelp(); break; }
     const { runTicketDuplicates } = await import('../skills/jtb/scripts/lib/ticket-command.mjs');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticketlens",
-  "version": "0.38.56",
+  "version": "0.39.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.43.3 -->
+<!-- jtb-skill-version: 0.44.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.
@@ -418,9 +418,9 @@ Recall notes are stored locally at `~/.ticketlens/recall/`. On a Pro account wit
 
 ---
 
-## Comment, Transition, Assign, Duplicates, Link, Update & Create — write back to the tracker (Pro)
+## Comment, Transition, Assign, Duplicates, Link, Update, Create & Worklog — write back to the tracker (Pro)
 
-Unlike Recall (a local note about a ticket), these seven commands write directly to the ticket's real tracker — Jira, GitHub, or Linear. Only dispatch a write when the user has actually asked for it — never as a routine end-of-session action the way Recall capture is. `duplicates` is read-only and safe to run more freely — it never mutates anything.
+Unlike Recall (a local note about a ticket), these eight commands write directly to the ticket's real tracker — Jira, GitHub, or Linear (`worklog` is Jira only). Only dispatch a write when the user has actually asked for it — never as a routine end-of-session action the way Recall capture is. `duplicates` is read-only and safe to run more freely — it never mutates anything.
 
 ```bash
 ticketlens comment PROD-1234 --body="Fixed in a2f9c1, deployed to staging."
@@ -436,6 +436,8 @@ ticketlens link PROD-1234 PROD-5678 --type="Duplicate" --confirm  # execute the
 ticketlens update PROD-1234 --title="Fix login on mobile"     # update title/description/labels/priority
 ticketlens update PROD-1234 --add-labels=urgent --remove-labels=stale
 ticketlens create --project=PROD --type="Task" --summary="Fix login on mobile"  # create a new ticket
+ticketlens worklog PROD-1234=1h30m                             # preview what would be logged — writes nothing
+ticketlens worklog PROD-1234=1h30m PROD-5678=45m --comment="Sprint work" --confirm  # log time on several tickets (Jira only)
 ```
 
 `transition` called with just a ticket key never mutates anything — it lists the tracker's current valid options (Jira: real workflow transitions for that issue; GitHub: open/closed; Linear: team-scoped workflow states). Only add `--target` **and** `--confirm` once the target has actually been confirmed with the user — `--confirm` is a deliberate two-step gate, not a formality to route around. Never guess a `--target` value; always list first, then use one of the names shown.
@@ -450,15 +452,17 @@ ticketlens create --project=PROD --type="Task" --summary="Fix login on mobile"
 
 `create` makes a brand-new ticket — there's no existing ticket to target, so `--project` (Jira project key / Linear team key) and `--type` (Jira issue type, ignored elsewhere) pick the destination instead of a ticket key. This is the highest-blast-radius command in the family: a bad `--project`/`--type` fabricates a real, hard-to-walk-back item in a live tracker. No `--confirm` gate — double-check the values with the user before calling it, since an invalid value surfaces the tracker's own error rather than a silent guess.
 
+`worklog KEY=DURATION [KEY=DURATION ...]` logs time worked on one or several tickets, always as the authenticated user — logging for someone else isn't supported, so don't attempt a workaround. Jira only: GitHub and Linear have no worklog API and are refused. Durations are hours and minutes only (`2h`, `90m`, `1h30m`, up to 24h each) — days and weeks are rejected because Jira defines them per instance; never guess a conversion, ask the user. `--started=` takes ISO 8601 with a time (default now; not in the future, not older than a year). Every entry's format and tracker are checked before any is written, so a malformed entry blocks the whole call; Jira-side failures (unknown ticket, no permission, time tracking off) are reported per ticket while writing, and a partial result names which tickets already landed — retry only the rest, never repeat them. A rate limit or 401 stops the batch. The same ticket twice in one call is refused, total time per call is capped at 24h, and comments at 2000 characters. A write that times out or gets a server error leaves a 10-minute hold on that ticket, because it may have landed — check Jira before logging it again. A worklog cannot be deleted through TicketLens, so without `--confirm` it only prints a preview — add `--confirm` only once the user has confirmed the durations and tickets, never as a formality to route around. Jira applies its own remaining-estimate and watcher-notification defaults. The MCP tool takes an `entries` array with a per-ticket `comment`/`started`; the CLI applies one `--comment`/`--started` to every ticket.
+
 `--attach=path1,path2` (comma-separated local file paths) is available on `comment` and `create` only. Images render as an inline thumbnail on Jira and Linear; GitHub has no attachment upload API, so `--attach` is unsupported there.
 
-The six write actions (comment/transition/assign/link/update/create) have a short local debounce (10s) against an accidental double-fire, and every write is appended to a local audit log (`~/.ticketlens/ticket-action-log.jsonl`). A write that times out is never retried automatically — surface the failure to the user rather than silently re-attempting, since a ticket write isn't naturally idempotent the way a Recall note save is. `duplicates` has neither, since nothing is written.
+The write actions (comment/transition/assign/link/update/create/worklog) have a short local debounce (10s) against an accidental double-fire, and every write is appended to a local audit log (`~/.ticketlens/ticket-action-log.jsonl`). A write that times out is never retried automatically — surface the failure to the user rather than silently re-attempting, since a ticket write isn't naturally idempotent the way a Recall note save is. `duplicates` has neither, since nothing is written.
 
-**Pick exactly one path per action — never both.** If this harness has TicketLens's MCP server configured (tools named `ticket_comment`/`ticket_transition`/`ticket_assign`/`ticket_duplicates`/`ticket_link`/`ticket_update`/`ticket_create` — often shown as `mcp__ticketlens__ticket_comment` etc. — visible in your tool list), **use those tools, not the bash commands above** — same license gate, same cooldown, same audit log. Only fall back to the bash form when the MCP tools are genuinely absent from your tool list; if that's because this project has never registered the server, see the `ticketlens mcp install` note above (Recall section) — same guidance applies here.
+**Pick exactly one path per action — never both.** If this harness has TicketLens's MCP server configured (tools named `ticket_comment`/`ticket_transition`/`ticket_assign`/`ticket_duplicates`/`ticket_link`/`ticket_update`/`ticket_create`/`ticket_worklog` — often shown as `mcp__ticketlens__ticket_comment` etc. — visible in your tool list), **use those tools, not the bash commands above** — same license gate, same cooldown, same audit log. Only fall back to the bash form when the MCP tools are genuinely absent from your tool list; if that's because this project has never registered the server, see the `ticketlens mcp install` note above (Recall section) — same guidance applies here.
 
 The same stale-schema caveat applies here — if a call rejects a parameter this document says exists (e.g. `attachments` on `ticket_comment`/`ticket_create`) right after an upgrade, see the MCP tool-cache staleness note above (Recall section).
 
-Requires a Pro license — on Free, all seven no-op with an upgrade hint on stderr.
+Requires a Pro license — on Free, all eight no-op with an upgrade hint on stderr.
 
 ---
 

package/skills/jtb/hooks/recall-nudge-lib.mjs

@@ -68,8 +68,10 @@ export function writeState(sessionId, state) {
   } catch { /* best-effort — a lost nudge counter is not worth failing the hook over */ }
 }
 
-// Two hours — how long a real capture in one directory counts as "recent
-// enough" to skip the Stop hook's nag, even from a brand-new session_id.
+// Two hours of IDLE time — how long a real capture in one directory counts as
+// "recent enough" to skip the Stop hook's nag, even from a brand-new session_id.
+// Sliding, not fixed: ongoing ticket work renews the marker (see
+// recall-nudge-stop.mjs, backlog #24), so only a full idle window lets it lapse.
 export const CAPTURE_FRESHNESS_MS = 2 * 60 * 60 * 1000;
 
 /**

package/skills/jtb/hooks/recall-nudge-stop.mjs

@@ -24,7 +24,9 @@
  * the same boundary for a DISMISSED nag: without it, a session that already
  * got its one nag and was told "genuinely nothing qualified" would nag
  * again after the next compaction/resume rollover, since that dismissal
- * was never recorded anywhere — only a real capture was.
+ * was never recorded anywhere — only a real capture was. Both markers slide:
+ * ongoing ticket work renews them while fresh, so only a full idle window
+ * (CAPTURE_FRESHNESS_MS) lets either lapse (backlog #24).
  *
  * Which of the two cases above actually blocks is governed by the effective
  * recallStrictness — the active profile's own explicit config-set value, or
@@ -102,7 +104,19 @@ if (isLicensed('pro') && cliToken && !hasRecentAutoCaptureAttempt(cwd)) {
 // Refreshed on every check, independent of the once-per-session gate below —
 // a capture that happens AFTER this session already nagged once must still
 // update the marker, or a later session_id rollover would find it stale.
-if (sawNoteAdd) writeLastCaptureAt(cwd, Date.now());
+//
+// Sliding window (backlog #24, 7th report): ongoing ticket work also renews a
+// marker that is still fresh, so it measures idle time, not time since the
+// last capture/nag. A fixed window expired mid-work (capture 17:48, nag 19:48
+// in a session with 23 silent Stops before it) and falsely claimed "nothing
+// was ever captured". Only a session that could itself nag (fetch + mutation)
+// renews, so non-ticket work and read-only lookups in the same cwd can't keep
+// a marker alive; a lapsed marker is never revived. Accepted trade-off: such
+// sessions chained in one cwd with gaps under the window keep suppressing.
+const now = Date.now();
+const isActiveTicketWork = sawFetch && sawMutatingAction;
+if (sawNoteAdd || (isActiveTicketWork && hasRecentCapture(cwd, now))) writeLastCaptureAt(cwd, now);
+if (isActiveTicketWork && hasRecentNag(cwd, now)) writeLastNagAt(cwd, now);
 
 const state = readState(sessionId);
 if (state.stopChecked) process.exit(0); // already asked once this session — respect the answer

package/skills/jtb/scripts/lib/adapters/jira-adapter.mjs

@@ -1,4 +1,5 @@
 import { fetchTicket, fetchCurrentUser, searchTickets, fetchStatuses, fetchProjects, fetchIssueTypes, postComment, getTransitions, postTransition, assignIssue, escapeJql, getIssueLinkTypes, postIssueLink, updateIssue, createIssue, DEFAULT_SEARCH_FIELDS } from '../jira-client.mjs';
+import { postWorklog } from '../jira-worklog-client.mjs';
 import { uploadAttachment, resolveMediaId } from '../jira-attachment-client.mjs';
 import { readAttachments } from '../attachment-uploader.mjs';
 import { buildMediaNode } from '../adf-converter.mjs';
@@ -39,6 +40,12 @@ export function createJiraAdapter(conn, { fetcher = globalThis.fetch } = {}) {
     searchTickets: (query, opts = {}) => searchTickets(query, { ...base, ...opts }),
     fetchStatuses: (opts = {}) => fetchStatuses({ ...base, ...opts }),
     addComment: (key, body, opts = {}) => postComment(key, body, { ...base, ...opts }),
+    /**
+     * Jira-only — GitHub and Linear have no worklog API, so their adapters
+     * deliberately lack this method and ticket-worklog.mjs refuses them
+     * before any write. Always logs as the authenticated user.
+     */
+    logWork: (key, entry, opts = {}) => postWorklog(key, entry, { ...base, ...opts }),
     getTransitions: (key, opts = {}) => getTransitions(key, { ...base, ...opts }),
     /**
      * Always re-fetches transitions fresh and resolves `target` against

package/skills/jtb/scripts/lib/api-utils.mjs

@@ -3,7 +3,7 @@
  * Centralised here to avoid triplicating the regex and warning logic.
  */
 
-export const DEFAULT_API_BASE = 'http://api.ticketlens.test';
+export const DEFAULT_API_BASE = 'https://api.ticketlens.app';
 export const DEFAULT_SITE_BASE = 'https://ticketlens.app';
 
 // Matches localhost, 127.0.0.1, and any hostname ending in .test or .local,

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

@@ -168,6 +168,10 @@ export function parseCommand(args) {
     return { command: 'assign', args: args.slice(1) };
   }
 
+  if (first === 'worklog') {
+    return { command: 'worklog', args: args.slice(1) };
+  }
+
   if (first === 'duplicates') {
     return { command: 'duplicates', args: args.slice(1) };
   }

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

@@ -58,6 +58,7 @@ export function printHelp({ stream = process.stdout } = {}) {
     `    ${s.brand('ticketlens')} comment ${s.dim('<TICKET-KEY> --body=... [--attach=...]')}  Post a comment to the tracker  ${s.dim('[Pro]')}`,
     `    ${s.brand('ticketlens')} transition ${s.dim('<TICKET-KEY> [--target=... --confirm]')}  Move ticket status  ${s.dim('[Pro]')}`,
     `    ${s.brand('ticketlens')} assign ${s.dim('<TICKET-KEY> --to=me')}      Assign a ticket to yourself  ${s.dim('[Pro]')}`,
+    `    ${s.brand('ticketlens')} worklog ${s.dim('<KEY=DURATION ...> [--comment=... --started=...] --confirm')}  Log time on Jira tickets  ${s.dim('[Pro] [Jira only]')}`,
     `    ${s.brand('ticketlens')} duplicates ${s.dim('<TICKET-KEY> [--threshold=N]')}  Find likely duplicate tickets  ${s.dim('[Pro]')}`,
     `    ${s.brand('ticketlens')} link ${s.dim('<SOURCE> <TARGET> [--type=... --confirm]')}  Link two tickets  ${s.dim('[Pro]')}`,
     `    ${s.brand('ticketlens')} update ${s.dim('<TICKET-KEY> [--title=... --description=... --priority=... --add-labels=... --remove-labels=...]')}  Update fields  ${s.dim('[Pro]')}`,
@@ -649,12 +650,12 @@ export function printMcpHelp({ stream = process.stdout } = {}) {
     `  native tools — ${s.cyan('fetch')}, ${s.cyan('triage')}, ${s.cyan('compliance')}, ${s.cyan('review')}, ${s.cyan('standup')}, ${s.cyan('pr')}, ${s.cyan('stats')}, ${s.cyan('history')},`,
     `  ${s.cyan('collisions')}, ${s.cyan('ledger')}, ${s.cyan('doctor')}, ${s.cyan('issue_types')}, ${s.cyan('recall_add')}, ${s.cyan('recall_update')}, ${s.cyan('recall_delete')},`,
     `  ${s.cyan('recall_search')}, ${s.cyan('ticket_comment')}, ${s.cyan('ticket_transition')}, ${s.cyan('ticket_assign')},`,
-    `  ${s.cyan('ticket_duplicates')}, ${s.cyan('ticket_link')}, ${s.cyan('ticket_update')}, ${s.cyan('ticket_create')} — every CLI action`,
+    `  ${s.cyan('ticket_duplicates')}, ${s.cyan('ticket_link')}, ${s.cyan('ticket_update')}, ${s.cyan('ticket_create')}, ${s.cyan('ticket_worklog')} — every CLI action`,
     `  now has an MCP tool, for any MCP-compatible AI harness, not just Claude Code.`,
     `  Thin adapter over the same code as ${s.cyan('TICKET-KEY')}/${s.cyan('doctor')}/${s.cyan('triage')}/${s.cyan('compliance')}/${s.cyan('review')}/`,
     `  ${s.cyan('standup')}/${s.cyan('pr')}/${s.cyan('stats')}/${s.cyan('history')}/${s.cyan('collisions')}/${s.cyan('ledger')}/${s.cyan('issue-types')}/${s.cyan('note add')}/${s.cyan('note patch')}/`,
     `  ${s.cyan('note delete')}/${s.cyan('recall')}/${s.cyan('comment')}/${s.cyan('transition')}/${s.cyan('assign')}/${s.cyan('duplicates')}/${s.cyan('link')}/`,
-    `  ${s.cyan('update')}/${s.cyan('create')} above.`,
+    `  ${s.cyan('update')}/${s.cyan('create')}/${s.cyan('worklog')} above.`,
     `  ${s.cyan('fetch')}, ${s.cyan('doctor')}, and ${s.cyan('standup')} are Free; ${s.cyan('triage')} is Free with some Pro/Team-gated`,
     `  options (see ${s.cyan('ticketlens triage --help')}); ${s.cyan('compliance')} and ${s.cyan('pr')} are Free, sharing a`,
     `  3-checks/month cap on their requirements-coverage section, Pro unlimited;`,
@@ -670,6 +671,8 @@ export function printMcpHelp({ stream = process.stdout } = {}) {
     `  "not available" instead of an empty result — every other tool needs Pro.`,
     `  ${s.cyan('ticket_transition')} is destructive when called with`,
     `  \`target\`+\`confirm: true\`; ${s.cyan('ticket_assign')} is currently self-assign only;`,
+    `  ${s.cyan('ticket_worklog')} is Jira-only, logs as you only, and writes nothing without`,
+    `  \`confirm: true\` (it previews instead) — a worklog cannot be deleted through TicketLens;`,
     `  ${s.cyan('ticket_duplicates')} is read-only; ${s.cyan('ticket_link')} on GitHub closes the source issue as a`,
     `  duplicate — different semantics than Jira/Linear's relationship-only add;`,
     `  ${s.cyan('ticket_update')} has no priority field on GitHub and can partially succeed;`,
@@ -793,6 +796,46 @@ export function printAssignHelp({ stream = process.stdout } = {}) {
   stream.write(lines.join('\n') + '\n');
 }
 
+export function printWorklogHelp({ stream = process.stdout } = {}) {
+  const s = createStyler({ isTTY: stream.isTTY });
+  const lines = [
+    '',
+    `  ${s.bold(s.brand('ticketlens'))} ${s.bold('worklog')} ${s.dim('KEY=DURATION [KEY=DURATION ...] --confirm')}  ${s.dim('[Pro]')}`,
+    '',
+    `  Log time worked on one or more tickets. ${s.dim('[Pro]')}`,
+    `  Jira only — GitHub and Linear have no worklog API. Always logs as you, the`,
+    `  authenticated user; logging for someone else isn't supported.`,
+    '',
+    `  Every entry's format and tracker are checked before any is written, so a typo blocks the`,
+    `  whole call. Jira-side failures (unknown ticket, no permission, time tracking off) are reported`,
+    `  per ticket while writing, naming what already landed so a retry never repeats it.`,
+    `  A worklog cannot be deleted through TicketLens, so nothing is written without`,
+    `  ${s.brand('--confirm')} — without it you get a preview. Jira applies its own`,
+    `  remaining-estimate and watcher-notification defaults.`,
+    '',
+    `  ${s.bold('OPTIONS')}`,
+    '',
+    `    ${s.brand('KEY=DURATION')}       One or more tickets, e.g. ${s.dim('PROJ-1=1h30m PROJ-2=45m')}. Hours and minutes`,
+    `                       only (${s.dim('2h')}, ${s.dim('90m')}, ${s.dim('1h30m')}), up to 24h each. Days and weeks are`,
+    `                       not accepted — Jira defines them per instance. Max 20 tickets, one`,
+    `                       entry per ticket, 24h in total per call.`,
+    `    ${s.brand('--comment')}=${s.dim('TEXT')}      Note attached to every worklog, up to 2000 characters ${s.dim('(optional; per-ticket notes need the MCP tool)')}`,
+    `    ${s.brand('--started')}=${s.dim('ISO')}       When the work started, with a time, e.g. ${s.dim('2026-09-18T10:00:00-07:00')}.`,
+    `                       Defaults to now; not in the future, not older than a year ${s.dim('(optional)')}`,
+    `    ${s.brand('--confirm')}            Required to write anything`,
+    `    ${s.brand('--profile')}=${s.dim('NAME')}      Connection profile to use ${s.dim('(optional)')}`,
+    `    ${s.brand('-h')}, ${s.brand('--help')}        Show this help`,
+    '',
+    `  ${s.bold('EXAMPLES')}`,
+    '',
+    `    ${s.dim('$')} ticketlens worklog PROJ-123=1h30m`,
+    `    ${s.dim('$')} ticketlens worklog PROJ-123=1h30m --confirm`,
+    `    ${s.dim('$')} ticketlens worklog PROJ-1=2h PROJ-2=45m --comment="Sprint work" --confirm`,
+    '',
+  ];
+  stream.write(lines.join('\n') + '\n');
+}
+
 export function printDuplicatesHelp({ stream = process.stdout } = {}) {
   const s = createStyler({ isTTY: stream.isTTY });
   const lines = [

package/skills/jtb/scripts/lib/jira-worklog-client.mjs

@@ -0,0 +1,84 @@
+/**
+ * Jira worklog write — split from jira-client.mjs (which sits at the file-size
+ * cap) the same way jira-attachment-client.mjs is: it reuses the client's own
+ * URL validation, auth header, and guardedFetch (SSRF/redirect guard), never
+ * its own copies.
+ */
+
+import { textToAdf } from './adf-converter.mjs';
+import { sanitizeUntrustedText } from './ansi.mjs';
+import { TICKET_KEY_PATTERN } from './cli.mjs';
+import { buildAuthHeader, guardedFetch, validateBaseUrl, defaultLookupFor } from './jira-client.mjs';
+
+/**
+ * Jira's own 400 text (errorMessages + per-field errors), so "Time tracking is
+ * disabled" or "You do not have permission to add worklog" reaches the caller
+ * instead of a bare status. Defensive about shape — the body is external data,
+ * so terminal control characters (an OSC 52 clipboard write, cursor movement)
+ * are stripped before the text can reach a caller's terminal.
+ */
+function summarizeJiraErrors(details) {
+  const messages = Array.isArray(details?.errorMessages) ? details.errorMessages : [];
+  const fields = details?.errors && typeof details.errors === 'object' ? Object.entries(details.errors).map(([field, msg]) => `${field}: ${msg}`) : [];
+  return sanitizeUntrustedText([...messages, ...fields].map(String).join('; ')).slice(0, 300);
+}
+
+/** Retry-After is delta-seconds or an HTTP date; only the former is usable as a wait, anything else is null. */
+function parseRetryAfterSeconds(value) {
+  const seconds = Number(value);
+  return Number.isInteger(seconds) && seconds > 0 ? seconds : null;
+}
+
+/**
+ * Adds a worklog to an issue, always as the authenticated user — Jira offers
+ * no way to log on someone else's behalf. `timeSpentSeconds` (not Jira's
+ * `timeSpent` string, whose `d`/`w` units are instance-configured) and
+ * `started` (required by Jira on create, `+0000` offset form only) are
+ * mandatory; both are checked before any network call. `comment` follows the
+ * same v3-ADF / v2-plain-string split as postComment. Jira's own estimate and
+ * watcher-notification defaults apply — deliberately not overridden here.
+ */
+export async function postWorklog(ticketKey, { timeSpentSeconds, started, comment } = {}, opts = {}) {
+  if (typeof ticketKey !== 'string' || !TICKET_KEY_PATTERN.test(ticketKey)) {
+    throw new TypeError('postWorklog: invalid ticket key — expected PROJ-123');
+  }
+  if (!Number.isInteger(timeSpentSeconds) || timeSpentSeconds <= 0) {
+    throw new TypeError('postWorklog: timeSpentSeconds must be a positive integer');
+  }
+  if (typeof started !== 'string' || !started) {
+    throw new TypeError('postWorklog: started is required — Jira rejects a worklog without it');
+  }
+  const { env = process.env, fetcher = globalThis.fetch, lookup = defaultLookupFor(fetcher), apiVersion = 2, timeoutMs = 10_000, allowPrivateIp = false } = opts;
+  validateBaseUrl(env.JIRA_BASE_URL, allowPrivateIp);
+  const baseUrl = env.JIRA_BASE_URL.replace(/\/$/, '');
+  const url = `${baseUrl}/rest/api/${apiVersion}/issue/${encodeURIComponent(ticketKey)}/worklog`;
+
+  const payload = { timeSpentSeconds, started };
+  if (comment !== undefined) payload.comment = apiVersion === 3 ? textToAdf(comment) : comment;
+  const fetchOpts = {
+    method: 'POST',
+    headers: { ...buildAuthHeader(env), 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+  };
+  if (timeoutMs) fetchOpts.signal = AbortSignal.timeout(timeoutMs);
+
+  const response = await guardedFetch(url, fetchOpts, { fetcher, lookup, allowPrivateIp });
+  if (!response.ok) {
+    let details;
+    try { details = await response.json(); } catch { /* body not JSON — fall through with no details */ }
+    const summary = summarizeJiraErrors(details);
+    const err = new Error(`Jira API error ${response.status} logging work on ${ticketKey}${summary ? `: ${summary}` : ''}`);
+    err.status = response.status;
+    err.details = details;
+    if (response.status === 429) err.rateLimit = { retryAfterSeconds: parseRetryAfterSeconds(response.headers?.get?.('retry-after')) };
+    throw err;
+  }
+  const raw = await response.json();
+  // Jira-supplied, then printed and audit-logged by callers: only a plain numeric id is trusted.
+  const id = /^\d+$/.test(String(raw.id)) ? String(raw.id) : undefined;
+  return {
+    id,
+    timeSpent: typeof raw.timeSpent === 'string' ? sanitizeUntrustedText(raw.timeSpent) : undefined,
+    url: `${baseUrl}/browse/${encodeURIComponent(ticketKey)}${id ? `?focusedWorklogId=${id}` : ''}`,
+  };
+}

package/skills/jtb/scripts/lib/mcp-server.mjs

@@ -25,6 +25,7 @@ import { runDoctor } from './doctor-command.mjs';
 import { runNoteAdd, runNotePatch, runNoteDelete } from './note-command.mjs';
 import { runRecall } from './recall-command.mjs';
 import { runTicketComment, runTicketTransitionList, runTicketTransition, runTicketAssign, runTicketDuplicates, runTicketLinkList, runTicketLink, runTicketUpdate, runTicketCreate } from './ticket-command.mjs';
+import { runTicketWorklogEntries } from './ticket-worklog.mjs';
 import { run as runFetchTicket } from '../fetch-ticket.mjs';
 import { run as runTriage } from '../fetch-my-tickets.mjs';
 import { runStats } from './run-stats.mjs';
@@ -526,6 +527,22 @@ async function callTicketAssign(args, { configDir, runTicketAssignFn }) {
   return ok ? { content } : { isError: true, content };
 }
 
+/**
+ * `entries` goes to the runner as structured data, never re-serialized into
+ * an argv — a comment reading `--confirm` cannot become a flag because no
+ * flag parsing happens on this path. Confirmation is the boolean `true`
+ * exactly; a truthy string like "yes" is not consent to write billable time.
+ */
+async function callTicketWorklog(args, { configDir, runTicketWorklogFn }) {
+  if (!Array.isArray(args.entries) || args.entries.length === 0) {
+    return { isError: true, content: [{ type: 'text', text: 'Missing required argument: entries (a non-empty array of { ticket, time })' }] };
+  }
+  const capture = capturingStream();
+  const { ok } = await runTicketWorklogFn(args.entries, { configDir, stream: capture, confirm: args.confirm === true, cliHints: false });
+  const content = [{ type: 'text', text: capture.text }];
+  return ok ? { content } : { isError: true, content };
+}
+
 async function callTicketDuplicates(args, { configDir, runTicketDuplicatesFn }) {
   if (!args.ticket) {
     return { isError: true, content: [{ type: 'text', text: 'Missing required argument: ticket' }] };
@@ -647,6 +664,7 @@ async function handleToolsCall(params, deps) {
   if (name === 'ticket_comment') return callTicketComment(args, deps);
   if (name === 'ticket_transition') return callTicketTransition(args, deps);
   if (name === 'ticket_assign') return callTicketAssign(args, deps);
+  if (name === 'ticket_worklog') return callTicketWorklog(args, deps);
   if (name === 'ticket_duplicates') return callTicketDuplicates(args, deps);
   if (name === 'ticket_link') return callTicketLink(args, deps);
   if (name === 'ticket_update') return callTicketUpdate(args, deps);
@@ -720,6 +738,7 @@ export function runMcpServer({
   runTicketTransitionListFn = runTicketTransitionList,
   runTicketTransitionFn = runTicketTransition,
   runTicketAssignFn = runTicketAssign,
+  runTicketWorklogFn = runTicketWorklogEntries,
   runTicketDuplicatesFn = runTicketDuplicates,
   runTicketLinkListFn = runTicketLinkList,
   runTicketLinkFn = runTicketLink,
@@ -736,7 +755,7 @@ export function runMcpServer({
   // Assembled once and passed straight through handleMessage to handleToolsCall,
   // which is the only place the individual functions are read — so a new tool
   // needs its dependency named here and in the parameter list above, nowhere else.
-  const deps = { configDir, runFetchTicketFn, runTriageFn, runDoctorFn, runStatsFn, runIssueTypesFn, runHistoryFn, runCollisionsFn, runNoteAddFn, runNotePatchFn, runNoteDeleteFn, runRecallFn, runTicketCommentFn, runTicketTransitionListFn, runTicketTransitionFn, runTicketAssignFn, runTicketDuplicatesFn, runTicketLinkListFn, runTicketLinkFn, runTicketUpdateFn, runTicketCreateFn };
+  const deps = { configDir, runFetchTicketFn, runTriageFn, runDoctorFn, runStatsFn, runIssueTypesFn, runHistoryFn, runCollisionsFn, runNoteAddFn, runNotePatchFn, runNoteDeleteFn, runRecallFn, runTicketCommentFn, runTicketTransitionListFn, runTicketTransitionFn, runTicketAssignFn, runTicketWorklogFn, runTicketDuplicatesFn, runTicketLinkListFn, runTicketLinkFn, runTicketUpdateFn, runTicketCreateFn };
 
   const rl = readline.createInterface({ input: stdin, terminal: false });
   let queue = Promise.resolve();

package/skills/jtb/scripts/lib/mcp-tool-schemas.mjs

@@ -249,6 +249,33 @@ export const TOOLS = [
       required: ['ticket', 'to'],
     },
   },
+  {
+    name: 'ticket_worklog',
+    description: 'Log time worked on one or more tickets in their tracker. Jira only — GitHub and Linear have no worklog API and are refused. Always logs as you, the authenticated user; logging for someone else is not supported. Destructive — writes directly to the live tracker, and there is no delete tool. Every entry\'s format and tracker are checked before any is written, so a malformed entry blocks the whole call; Jira-side failures (unknown ticket, no permission, time tracking off) are reported per ticket while writing, and a partial result names which tickets already landed — retry only the rest. A rate limit or 401 stops the batch. Called without `confirm: true` it writes nothing and returns a preview of what would be logged; call again with `confirm: true` to log. Jira applies its own remaining-estimate and watcher-notification defaults. Requires a TicketLens Pro license.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        entries: {
+          type: 'array',
+          minItems: 1,
+          maxItems: 20,
+          description: 'One entry per ticket, at most 20 per call, at most 24h in total per call. The same ticket twice in one call is refused.',
+          items: {
+            type: 'object',
+            properties: {
+              ticket: { type: 'string', description: 'Ticket key, e.g. PROJ-123.' },
+              time: { type: 'string', description: 'Time spent as hours and minutes — "1h30m", "90m", "2h". Up to 24h. Days and weeks are not accepted (Jira defines them per instance).' },
+              started: { type: 'string', description: 'When the work started, ISO 8601 with a time, e.g. "2026-09-18T10:00:00-07:00". Defaults to now. Cannot be in the future or older than a year.' },
+              comment: { type: 'string', description: 'Optional note attached to the worklog, up to 2000 characters.' },
+            },
+            required: ['ticket', 'time'],
+          },
+        },
+        confirm: { type: 'boolean', description: 'Must be true to actually log the time. Omit it to get a preview with nothing written.' },
+      },
+      required: ['entries'],
+    },
+  },
   {
     name: 'ticket_duplicates',
     description: 'Find likely duplicate tickets in the same project (Jira/GitHub/Linear). Read-only — never links or changes anything. On Jira, any ticket already linked as a "Duplicate" is always included first (a confirmed relationship, not a guess); everything else comes from a local, approximate title/description overlap score, since no tracker scores similarity server-side. That scorer can miss real duplicates as easily as it over-matches, so an empty result means none were found, not a guarantee that none exist. Requires a TicketLens Pro license.',

package/skills/jtb/scripts/lib/ticket-action-log.mjs

@@ -32,7 +32,7 @@ function logPath(configDir) {
 }
 
 /**
- * @param {{ ticketKey: string, action: 'comment'|'transition', actor: string, tracker: string, detail?: object }} entry
+ * @param {{ ticketKey: string, action: string, actor: string, tracker: string, detail?: object }} entry
  * @param {{ configDir?: string, now?: () => Date }} [opts]
  */
 export function logAction({ ticketKey, action, actor, tracker, detail = {} }, {

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

@@ -23,7 +23,7 @@ import { scoreCandidates } from './duplicate-scorer.mjs';
 import { MAX_ATTACHMENTS } from './attachment-uploader.mjs';
 import { createStyler } from './ansi.mjs';
 
-function parseFlag(cmdArgs, name) {
+export function parseFlag(cmdArgs, name) {
   return cmdArgs.find(a => a.startsWith(`--${name}=`))?.slice(name.length + 3);
 }
 
@@ -77,7 +77,7 @@ export function classifyWriteFailure(err) {
   return { kind: 'terminal', status: err.status, details: err.details };
 }
 
-function formatWriteFailure(ticketKey, err) {
+export function formatWriteFailure(ticketKey, err) {
   const classification = classifyWriteFailure(err);
   switch (classification.kind) {
     case 'rate-limited': {
@@ -201,7 +201,7 @@ function formatUpdateResult(ticketKey, { applied, errors }, s) {
   return `  Nothing updated on ${ticketKey}. Failed: ${errorText}.\n`;
 }
 
-function requireLicense(isLicensedFn, configDir, commandName, stream) {
+export function requireLicense(isLicensedFn, configDir, commandName, stream) {
   if (isLicensedFn('pro', configDir)) return true;
   showUpgradePrompt('pro', commandName, { stream });
   return false;
@@ -236,7 +236,7 @@ function requireTicketKey(cmdArgs, usage, stream) {
  * `runTicketCreate`'s profile/project mismatch safety net — have it without
  * re-resolving.
  */
-function resolveTicketAdapter(ticketKey, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream }) {
+export function resolveTicketAdapter(ticketKey, cmdArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream }) {
   const profileName = parseFlag(cmdArgs, 'profile');
   const conn = resolveConnectionFn(ticketKey, {
     configDir,

package/skills/jtb/scripts/lib/ticket-worklog.mjs

@@ -0,0 +1,342 @@
+/**
+ * Implements `ticketlens worklog` and the `ticket_worklog` MCP tool: logs time
+ * against one or many tickets. Jira-only (GitHub/Linear have no worklog API),
+ * always as the authenticated user, Pro-gated like every ticket write.
+ *
+ * Time entries feed billing/payroll and have no delete path here, so the shape
+ * is deliberately stricter than ticket_comment:
+ *  - every entry is validated and resolved BEFORE any write — a typo in entry
+ *    3 never leaves entries 1–2 logged;
+ *  - nothing is written without an explicit confirm (a preview is shown);
+ *  - runtime failures are reported per ticket, with what already landed named
+ *    so a retry never repeats it; a rate-limit or 401 halts the batch; and
+ *    local bookkeeping failing after a landed write never reads as failure
+ *    (a retry would double the time).
+ * Jira has no public bulk-worklog endpoint, so a batch is sequential POSTs.
+ */
+
+import os from 'node:os';
+import { DEFAULT_CONFIG_DIR } from './config.mjs';
+import { isLicensed } from './license.mjs';
+import { resolveConnection } from './profile-resolver.mjs';
+import { resolveAdapter } from './resolve-adapter.mjs';
+import { checkCooldown, recordAction } from './ticket-action-cooldown.mjs';
+import { logAction } from './ticket-action-log.mjs';
+import { TICKET_KEY_PATTERN, normalizeTicketKey } from './cli.mjs';
+import { createStyler, sanitizeUntrustedText } from './ansi.mjs';
+import { parseFlag, requireLicense, resolveTicketAdapter, formatWriteFailure, classifyWriteFailure } from './ticket-command.mjs';
+import { parseDuration, parseStarted, formatDuration } from './worklog-duration.mjs';
+
+export const MAX_WORKLOG_ENTRIES = 20;
+/** One call may log at most a day's worth in total — the per-entry 24h cap alone allows 20 x 24h. */
+export const MAX_WORKLOG_TOTAL_SECONDS = 86_400;
+export const MAX_COMMENT_CHARS = 2000;
+/**
+ * A timed-out or 5xx write may have landed. The 10s double-fire debounce is far
+ * too short to stop a retry of that — minutes, until the user has checked Jira.
+ */
+const UNCONFIRMED_WINDOW_MS = 10 * 60 * 1000;
+const USAGE = 'Usage: ticketlens worklog KEY=DURATION [KEY=DURATION ...] [--comment="..."] [--started=ISO] [--profile=NAME] --confirm\n';
+const COMMENT_PREVIEW_CHARS = 60;
+
+const invalid = (error) => ({ error });
+const refused = (reason) => ({ ok: false, reason, results: [] });
+const fromResult = (result, valueKey) => (result.ok ? { value: result[valueKey] } : invalid(result.error));
+
+function parseTicket(raw) {
+  if (typeof raw !== 'string') return invalid('"ticket" must be a string like PROJ-123.');
+  const key = normalizeTicketKey(raw.trim());
+  if (!TICKET_KEY_PATTERN.test(key)) return invalid(`${JSON.stringify(raw)} is not a valid ticket key.`);
+  // Jira numbers never have leading zeros; PROJ-01 would slip past duplicate/cooldown checks keyed on PROJ-1.
+  if (/-0\d/.test(key)) return invalid(`${JSON.stringify(raw)} has a leading zero in its number — did you mean ${key.replace(/-0+(?=\d)/, '-')}?`);
+  return { value: key };
+}
+
+function parseComment(raw) {
+  if (raw === undefined || raw === null || raw === '') return { value: undefined };
+  if (typeof raw !== 'string') return invalid('"comment" must be a string.');
+  return raw.length <= MAX_COMMENT_CHARS ? { value: raw } : invalid(`"comment" is ${raw.length} characters — at most ${MAX_COMMENT_CHARS}.`);
+}
+
+/** @returns {{ item?: object, errors?: string[] }} */
+function parseEntry(raw, index, now) {
+  const label = `Entry ${index + 1}`;
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    return { errors: [`${label}: expected an object with "ticket" and "time".`] };
+  }
+  const parts = {
+    ticket: parseTicket(raw.ticket),
+    seconds: fromResult(parseDuration(raw.time), 'seconds'),
+    started: fromResult(parseStarted(raw.started ?? undefined, { now }), 'started'),
+    comment: parseComment(raw.comment),
+  };
+  const errors = Object.values(parts).filter(p => p.error).map(p => `${label}: ${p.error}`);
+  if (errors.length) return { errors };
+  return { item: { ticket: parts.ticket.value, seconds: parts.seconds.value, started: parts.started.value, comment: parts.comment.value } };
+}
+
+function findDuplicates(parsed) {
+  const seen = new Set();
+  const errors = [];
+  parsed.forEach((p, index) => {
+    if (!p.item) return;
+    if (seen.has(p.item.ticket)) errors.push(`Entry ${index + 1}: ${p.item.ticket} appears more than once — one worklog per ticket per call.`);
+    seen.add(p.item.ticket);
+  });
+  return errors;
+}
+
+function findTotalOverrun(parsed) {
+  const total = parsed.reduce((sum, p) => sum + (p.item?.seconds ?? 0), 0);
+  return total > MAX_WORKLOG_TOTAL_SECONDS ? [`Total time across entries is ${formatDuration(total)} — at most 24h per call. Split it across separate calls.`] : [];
+}
+
+/** @returns {object[] | null} validated items, or null after writing every error found */
+function parseEntries(entries, { now, stream }) {
+  if (!Array.isArray(entries) || entries.length === 0) {
+    stream.write('  Provide at least one entry.\n');
+    return null;
+  }
+  if (entries.length > MAX_WORKLOG_ENTRIES) {
+    stream.write(`  Too many entries (${entries.length}) — at most ${MAX_WORKLOG_ENTRIES} per call.\n`);
+    return null;
+  }
+  const parsed = entries.map((raw, index) => parseEntry(raw, index, now));
+  const errors = [...parsed.flatMap(p => p.errors ?? []), ...findDuplicates(parsed), ...findTotalOverrun(parsed)];
+  if (errors.length) {
+    stream.write(errors.map(e => `  ${e}\n`).join(''));
+    return null;
+  }
+  return parsed.map(p => p.item);
+}
+
+/** @returns {object[] | null} items with their adapter attached, or null after writing every problem */
+/** Connection resolution warns once per entry; an identical line (a profile-ambiguity warning) is shown once. */
+function onceStream(stream) {
+  const seen = new Set();
+  return { isTTY: stream.isTTY, write: (text) => (seen.has(text) ? true : (seen.add(text), stream.write(text))) };
+}
+
+function resolveItems(items, { profile, configDir, resolveConnectionFn, resolveAdapterFn, stream }) {
+  const profileArgs = profile ? [`--profile=${profile}`] : [];
+  const resolveStream = onceStream(stream);
+  const resolved = items.map(item => {
+    const found = resolveTicketAdapter(item.ticket, profileArgs, { configDir, resolveConnectionFn, resolveAdapterFn, stream: resolveStream });
+    if (found && typeof found.adapter.logWork !== 'function') {
+      stream.write(`  ${item.ticket}: worklogs are only supported on Jira — this ticket is on ${found.adapter.type}.\n`);
+      return null;
+    }
+    return found && { ...item, adapter: found.adapter };
+  });
+  return resolved.includes(null) ? null : resolved;
+}
+
+function writePreview(items, { stream, cliHints }) {
+  const s = createStyler({ isTTY: stream.isTTY });
+  stream.write(`  Would log ${items.length} worklog${items.length === 1 ? '' : 's'}:\n\n`);
+  for (const item of items) {
+    const note = item.comment ? `  — ${sanitizeUntrustedText(item.comment.replace(/\s+/g, ' ')).slice(0, COMMENT_PREVIEW_CHARS)}` : '';
+    stream.write(`    ${s.brand(s.bold(item.ticket))}  ${formatDuration(item.seconds)}  started ${item.started}${note}\n`);
+  }
+  stream.write(cliHints
+    ? `\n  Refusing to log without --confirm. Re-run with --confirm once you've reviewed the entries.\n`
+    : `\n  Refusing to log without confirm: true. Call again with confirm: true once you've reviewed the entries.\n`);
+}
+
+/**
+ * Runs after the write already landed — a failure here must never be reported
+ * as a failed write. Audit first (it is the record of billable time), each in
+ * its own try so one failing never skips the other.
+ */
+function recordBookkeeping(item, result, { configDir, recordActionFn, logActionFn, actor, stream, source }) {
+  const attempt = (label, fn) => {
+    try { fn(); } catch (err) {
+      stream.write(`  ${item.ticket} logged, but local ${label} record failed: ${sanitizeUntrustedText(String(err.message))}. Do not re-run — the time is already on the ticket.\n`);
+    }
+  };
+  attempt('audit', () => logActionFn({
+    ticketKey: item.ticket,
+    action: 'worklog',
+    actor,
+    tracker: item.adapter.type,
+    detail: { id: result.id, seconds: item.seconds, started: item.started, hasComment: item.comment !== undefined, source },
+  }, { configDir }));
+  attempt('cooldown', () => recordActionFn(item.ticket, 'worklog', { configDir }));
+}
+
+/** Tracker text is untrusted: strip terminal control characters per line, keeping the line structure. */
+const safeLines = (text) => text.split('\n').map(sanitizeUntrustedText).join('\n');
+
+/** Checked before every write: a recent worklog, or a recent write whose outcome is still unknown. */
+function skipReason(item, { configDir, checkCooldownFn }) {
+  const unconfirmed = checkCooldownFn(item.ticket, 'worklog-unconfirmed', { configDir, cooldownMs: UNCONFIRMED_WINDOW_MS });
+  if (unconfirmed.active) {
+    return `  Skipped ${item.ticket} — an earlier write to it ended without a confirmed result (timeout or server error) ${Math.ceil(unconfirmed.remainingMs / 60000)}m ago and may have already landed. Check the ticket in Jira before logging again.\n`;
+  }
+  const recent = checkCooldownFn(item.ticket, 'worklog', { configDir });
+  if (recent.active) {
+    return `  Skipped ${item.ticket} — a worklog was already logged ${Math.ceil(recent.remainingMs / 1000)}s ago and is not repeated. Check the ticket before logging again.\n`;
+  }
+  return null;
+}
+
+/** Timeout / 5xx: the POST may have landed. Leave a long cooldown and an audit line so a retry can't silently double-bill. */
+function recordUnconfirmed(item, classification, { configDir, recordActionFn, logActionFn, actor, stream, source }) {
+  if (classification.kind !== 'network-or-timeout' && classification.kind !== 'server-error') return;
+  try {
+    logActionFn({ ticketKey: item.ticket, action: 'worklog-unconfirmed', actor, tracker: item.adapter.type, detail: { seconds: item.seconds, started: item.started, kind: classification.kind, source } }, { configDir });
+    recordActionFn(item.ticket, 'worklog-unconfirmed', { configDir });
+  } catch (err) {
+    stream.write(`  Could not record the unconfirmed write to ${item.ticket} locally: ${sanitizeUntrustedText(err.message)}.\n`);
+  }
+}
+
+async function logOne(item, ctx) {
+  const { stream } = ctx;
+  const skip = skipReason(item, ctx);
+  if (skip) {
+    stream.write(skip);
+    return { ticket: item.ticket, status: 'skipped', reason: 'cooldown' };
+  }
+  const entry = { timeSpentSeconds: item.seconds, started: item.started, ...(item.comment !== undefined && { comment: item.comment }) };
+  let result;
+  try {
+    result = await item.adapter.logWork(item.ticket, entry);
+  } catch (err) {
+    const classification = classifyWriteFailure(err);
+    stream.write(safeLines(formatWriteFailure(item.ticket, err)));
+    recordUnconfirmed(item, classification, ctx);
+    return { ticket: item.ticket, status: 'failed', error: sanitizeUntrustedText(String(err.message)), kind: classification.kind, httpStatus: err.status };
+  }
+  const s = createStyler({ isTTY: stream.isTTY });
+  stream.write(`  ${s.green('✔')} ${s.brand(s.bold(item.ticket))} logged ${formatDuration(item.seconds)}${result.url ? ` (${sanitizeUntrustedText(result.url)})` : ''}\n`);
+  recordBookkeeping(item, result, ctx);
+  return { ticket: item.ticket, status: 'logged', id: result.id, seconds: item.seconds, url: result.url };
+}
+
+/** A rate limit or a 401 fails every remaining entry the same way — stop instead of firing doomed POSTs. */
+function haltReason(result) {
+  if (result.kind === 'rate-limited' || result.httpStatus === 429) return 'a tracker rate limit';
+  if (result.httpStatus === 401) return 'an authentication failure (401)';
+  return null;
+}
+
+/** Names what landed and what to retry, so a caller (often an AI) never re-sends a worklog that already went through. */
+function writeBatchSummary(results, stream) {
+  const logged = results.filter(r => r.status === 'logged').map(r => r.ticket);
+  const pending = results.filter(r => r.status !== 'logged').map(r => r.ticket);
+  stream.write(`\n  Logged ${logged.length} of ${results.length} worklogs.\n`);
+  if (logged.length && pending.length) stream.write(`  Already logged (do not repeat): ${logged.join(', ')}.\n`);
+  if (pending.length) stream.write(`  Retry only: ${pending.join(', ')}.\n`);
+}
+
+async function logAll(items, ctx) {
+  const results = [];
+  let haltedBy = null;
+  for (const item of items) {
+    if (haltedBy) {
+      ctx.stream.write(`  ${item.ticket} not attempted — the batch stopped after ${haltedBy}. Run ${item.ticket} again later.\n`);
+      results.push({ ticket: item.ticket, status: 'skipped', reason: 'batch-halted' });
+      continue;
+    }
+    const result = await logOne(item, ctx);
+    results.push(result);
+    haltedBy = haltReason(result);
+  }
+  if (results.length > 1) writeBatchSummary(results, ctx.stream);
+  return { ok: results.every(r => r.status === 'logged'), results };
+}
+
+/**
+ * Core entry point, shared by the CLI parser below and the MCP tool (which
+ * passes structured entries directly — a comment never round-trips through
+ * an argv string).
+ *
+ * @param {Array<{ ticket: string, time: string, started?: string, comment?: string }>} entries
+ * @param {{ confirm?: boolean, profile?: string, cliHints?: boolean }} [deps]
+ * @returns {Promise<{ ok: boolean, reason?: string, results: object[] }>}
+ */
+export async function runTicketWorklogEntries(entries, {
+  configDir = DEFAULT_CONFIG_DIR,
+  stream = process.stderr,
+  confirm = false,
+  profile,
+  cliHints = true,
+  isLicensedFn = isLicensed,
+  resolveConnectionFn = resolveConnection,
+  resolveAdapterFn = resolveAdapter,
+  checkCooldownFn = checkCooldown,
+  recordActionFn = recordAction,
+  logActionFn = logAction,
+  actor = os.userInfo().username,
+  now = () => Date.now(),
+} = {}) {
+  if (!requireLicense(isLicensedFn, configDir, 'ticketlens worklog', stream)) return refused();
+
+  const items = parseEntries(entries, { now, stream });
+  if (!items) return refused();
+  const resolved = resolveItems(items, { profile, configDir, resolveConnectionFn, resolveAdapterFn, stream });
+  if (!resolved) return refused();
+
+  if (confirm !== true) {
+    writePreview(resolved, { stream, cliHints });
+    return refused('confirm-required');
+  }
+  return logAll(resolved, { configDir, checkCooldownFn, recordActionFn, logActionFn, actor, stream, source: cliHints ? 'cli' : 'mcp' });
+}
+
+function parsePair(arg) {
+  const at = arg.indexOf('=');
+  return at > 0 ? { ticket: arg.slice(0, at), time: arg.slice(at + 1) } : null;
+}
+
+const VALUE_FLAGS = ['comment', 'started', 'profile'];
+
+/**
+ * Refuses what parseFlag would silently ignore: a misspelled `--startd=` would
+ * quietly bill "now", an empty `--started=` likewise, and a repeated flag would
+ * silently keep only the first. Time entries are too costly to guess about.
+ * @returns {string[]} one message per problem, empty when the flags are clean
+ */
+function flagErrors(flags) {
+  const errors = [];
+  const seen = new Set();
+  for (const flag of flags) {
+    const [name, ...rest] = flag.slice(2).split('=');
+    const hasValue = flag.includes('=');
+    if (flag === '--confirm') continue;
+    if (!VALUE_FLAGS.includes(name) || !hasValue) {
+      errors.push(`Unknown option ${hasValue ? `--${name}` : flag}${VALUE_FLAGS.includes(name) ? ` (use --${name}=VALUE)` : ''}.`);
+    } else if (!rest.join('=')) {
+      errors.push(`--${name} needs a value, e.g. --${name}=...`);
+    } else if (seen.has(name)) {
+      errors.push(`--${name} was given more than once.`);
+    }
+    seen.add(name);
+  }
+  return errors;
+}
+
+/**
+ * @param {string[]} cmdArgs - ['PROJ-1=1h30m', 'PROJ-2=45m', '--comment=...', '--started=...', '--confirm']
+ *   `--comment`/`--started` apply to every ticket; per-ticket values need the MCP tool.
+ */
+export async function runTicketWorklog(cmdArgs, { stream = process.stderr, ...deps } = {}) {
+  const pairs = cmdArgs.filter(a => !a.startsWith('--')).map(parsePair);
+  if (pairs.length === 0 || pairs.includes(null)) {
+    stream.write(USAGE);
+    return refused();
+  }
+  const errors = flagErrors(cmdArgs.filter(a => a.startsWith('--')));
+  if (errors.length) {
+    stream.write(errors.map(e => `  ${e}\n`).join('') + USAGE);
+    return refused();
+  }
+  const shared = Object.fromEntries(['comment', 'started'].map(name => [name, parseFlag(cmdArgs, name)]).filter(([, value]) => value));
+  return runTicketWorklogEntries(pairs.map(pair => ({ ...pair, ...shared })), {
+    ...deps,
+    stream,
+    confirm: cmdArgs.includes('--confirm'),
+    profile: parseFlag(cmdArgs, 'profile'),
+  });
+}

package/skills/jtb/scripts/lib/worklog-duration.mjs

@@ -0,0 +1,85 @@
+/**
+ * Duration and start-time parsing for worklogs. Jira's own `timeSpent` string
+ * treats `d`/`w` as instance-configured (a "day" is whatever the admin set) and
+ * is mutually exclusive with `timeSpentSeconds`, so durations are parsed here
+ * into exact seconds — hours and minutes only, deterministic on every instance.
+ */
+
+/** A single worklog above a full day is far more likely a typo (`90h` for `90m`) than real. */
+export const MAX_WORKLOG_SECONDS = 86_400;
+
+/** Tolerance for a `started` slightly ahead of this machine's clock. */
+export const MAX_FUTURE_SKEW_MS = 5 * 60 * 1000;
+
+/** Older than this is far more likely a year typo (2016 for 2026) than a real backfill. */
+export const MAX_PAST_MS = 365 * 24 * 60 * 60 * 1000;
+
+const DURATION_PATTERN = /^(?:(\d{1,4})h)?(?:(\d{1,4})m)?$/;
+const DAYS_OR_WEEKS_PATTERN = /\d[dw]/;
+const STARTED_PATTERN = /^(\d{4})-(\d{2})-(\d{2})T\d{2}:\d{2}/;
+const DATE_ONLY_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+
+const fail = (error) => ({ ok: false, error });
+
+/**
+ * @param {unknown} input - e.g. "1h30m", "1h 30m", "90m"
+ * @returns {{ ok: true, seconds: number } | { ok: false, error: string }}
+ */
+export function parseDuration(input) {
+  if (typeof input !== 'string' || !input.trim()) {
+    return fail('Duration is required, e.g. "1h30m" or "45m".');
+  }
+  const compact = input.replace(/\s+/g, '').toLowerCase();
+  if (DAYS_OR_WEEKS_PATTERN.test(compact)) {
+    return fail(`Days and weeks are not supported — Jira defines them per instance. Express ${JSON.stringify(input)} in hours, e.g. "8h".`);
+  }
+  const match = DURATION_PATTERN.exec(compact);
+  if (!match) {
+    return fail(`Invalid duration ${JSON.stringify(input)} — use hours and minutes, e.g. "1h30m" or "90m".`);
+  }
+  const seconds = Number(match[1] ?? 0) * 3600 + Number(match[2] ?? 0) * 60;
+  if (seconds <= 0) return fail('Duration must be greater than zero.');
+  if (seconds > MAX_WORKLOG_SECONDS) return fail(`Duration ${JSON.stringify(input)} exceeds the 24h per-entry limit.`);
+  return { ok: true, seconds };
+}
+
+/** @param {number} seconds - a positive multiple of 60 */
+export function formatDuration(seconds) {
+  const hours = Math.floor(seconds / 3600);
+  const minutes = Math.floor((seconds % 3600) / 60);
+  return [hours && `${hours}h`, minutes && `${minutes}m`].filter(Boolean).join(' ') || '0m';
+}
+
+/** Jira rejects `Z` and `+00:00` here — only the `+0000` form is accepted. */
+export function toJiraDateTime(date) {
+  return date.toISOString().replace('Z', '+0000');
+}
+
+/** Rejects an out-of-range day (2026-02-30) that `Date` would silently roll into the next month. */
+function hasValidDay(year, month, day) {
+  return day >= 1 && day <= new Date(Date.UTC(year, month, 0)).getUTCDate();
+}
+
+/**
+ * @param {unknown} input - ISO 8601 with a time component; omitted means now.
+ *   A timestamp with no offset is read as this machine's local time.
+ * @param {{ now?: () => number }} [opts]
+ * @returns {{ ok: true, started: string } | { ok: false, error: string }}
+ */
+export function parseStarted(input, { now = () => Date.now() } = {}) {
+  if (input === undefined) return { ok: true, started: toJiraDateTime(new Date(now())) };
+
+  const invalid = fail(`Invalid started value ${JSON.stringify(input)} — use ISO 8601, e.g. "2026-09-18T10:00:00-07:00".`);
+  if (typeof input !== 'string') return invalid;
+
+  const trimmed = input.trim();
+  if (DATE_ONLY_PATTERN.test(trimmed)) {
+    return fail('Started needs a time, not just a date — e.g. "2026-09-18T10:00:00-07:00".');
+  }
+  const match = STARTED_PATTERN.exec(trimmed);
+  const ms = Date.parse(trimmed);
+  if (!match || Number.isNaN(ms) || !hasValidDay(Number(match[1]), Number(match[2]), Number(match[3]))) return invalid;
+  if (ms > now() + MAX_FUTURE_SKEW_MS) return fail('Started is in the future — worklogs record time already spent.');
+  if (ms < now() - MAX_PAST_MS) return fail('Started is older than a year — check the year. Backfilling that far is not supported here.');
+  return { ok: true, started: toJiraDateTime(new Date(ms)) };
+}