@knpkv/jira-clockify 1.2.1 → 1.4.0

package/nvim/lua/jcf/state.lua

@@ -2,8 +2,17 @@ local M = {}
 local uv = vim.loop or vim.uv
 local cached = { active = false }
 local last_key = nil
+local last_path = nil
 local poll_timer = nil
 local poll_job = nil
+-- Config captured by `start_poll`, so the command and its lock/stamp paths stay
+-- stable for the lifetime of the timer.
+local poll_config = nil
+-- The interval `start_poll` was given. Needed away from that function because it
+-- is also the machine's poll budget, not just this editor's tick spacing.
+local poll_interval_ms = nil
+local poll_once
+local arm_poll
 
 -- The cache key has to change on every write. `mtime.sec` alone does not: a
 -- write landing in the same filesystem second as the previous read is
@@ -30,12 +39,14 @@ function M.read(state_path)
     -- spawning `jcf timer status` every tick against a timer that isn't there.
     cached = { active = false }
     last_key = nil
+    last_path = nil
     return cached
   end
   local key = stat_key(stat)
-  if key == last_key then
+  if path == last_path and key == last_key then
     return cached
   end
+  last_path = path
   last_key = key
   local f = io.open(path, "r")
   if f then
@@ -57,7 +68,9 @@ end
 -- multiplied by the number of open editors. Hence: at most one job in flight,
 -- owned by nvim (never detached, so VimLeave and jobstop can actually kill it),
 -- under a watchdog. When no timer is running locally there is nothing to
--- reconcile, so the spawn is skipped entirely.
+-- reconcile, so the spawn is skipped entirely. That bounds one editor to one
+-- poll; the lock below bounds the whole machine to one, which is the part that
+-- actually decides the cost when many editors are open.
 -- Backstop only. `jcf timer status` bounds every network call it can make, but
 -- not all at the same value: an expired Jira token costs up to
 -- `REFRESH_TIMEOUT` (30s, in @knpkv/jira-cli's JiraAuth) before any command
@@ -88,19 +101,139 @@ local POLL_TIMEOUT_MS = 120000
 -- `invalid_grant`. No client-side design can close that window.
 local POLL_STOP_GRACE_MS = 35000
 
+-- ---------------------------------------------------------------------------
+-- Cross-editor lock: one `jcf timer status` per machine, not per editor.
+-- ---------------------------------------------------------------------------
+--
+-- The single-flight guard above is process-local. It bounds one nvim to one
+-- poll and says nothing about the others, so with an editor open per project it
+-- does not bound anything that matters: 19 editors on a 30s timer is 19 cold
+-- Node starts every 30s, each making the same four Clockify calls to reconcile
+-- the same single global timer.
+--
+-- The work is inherently shared — one `~/.jcf/state.json`, one running timer —
+-- so exactly one editor should do it and the rest should read the file it
+-- refreshes, which `M.read` already does off an mtime cache. Coordination uses
+-- util-linux `flock`: every editor starts a non-blocking contender, the kernel
+-- lets exactly one exec `jcf`, and every loser exits without starting Node.
+-- `--no-fork` leaves the lock attached to the `jcf` process itself. If nvim is
+-- SIGKILLed, its child therefore keeps the lock until the poll really exits.
+--
+-- The lock is half of it. It bounds how many polls run *at once*, and because
+-- it is released as soon as the CLI exits, it says nothing about how often they
+-- run — 19 editors would still spawn ~19 times per interval, just never two at
+-- the same moment. The poll stamp below is what bounds the rate, and the two
+-- together are what make the "per machine" claim above true.
+--
+-- No directory is created for it. The lock sits beside the CLI's fixed state
+-- authority. Neovim's configurable `state_path` only changes which file the UI
+-- reads; `jcf timer status` still mutates `~/.jcf/state.json`, so every editor
+-- must coordinate on that one path regardless of its display configuration.
+local function cli_state_path()
+  return vim.fn.expand("~/.jcf/state.json")
+end
+
+local function lock_path()
+  return vim.fn.fnamemodify(cli_state_path(), ":h") .. "/poll.lock"
+end
+
+-- ---------------------------------------------------------------------------
+-- Poll stamp: the lock bounds overlap, this bounds rate.
+-- ---------------------------------------------------------------------------
+--
+-- The lock is held only while `jcf timer status` runs — a second or two — and
+-- released the moment it exits. That makes two polls never overlap, which is not
+-- the same as making them rare: 19 editors on a 30s timer tick every ~1.6s
+-- between them, and by then the lock is free again, so nearly every tick would
+-- still spawn. The lock alone therefore delivers ~19 polls per interval, the
+-- number it exists to avoid.
+--
+-- What actually bounds the machine is a record that survives the release. Each
+-- finished attempt writes a stamp file before releasing the lock, and a tick
+-- that finds the stamp younger than one interval skips. Failed attempts count:
+-- otherwise every de-phased editor would retry the same persistent failure in
+-- turn. Readers keep the last state file until the next attempt. That is the
+-- whole rate limit, and it is what lets the editors stay de-phased without
+-- multiplying the work.
+--
+-- The CLI owns the write so no successor can acquire the lock between process
+-- exit and the stamp becoming visible.
+local function stamp_path()
+  return vim.fn.fnamemodify(cli_state_path(), ":h") .. "/poll.stamp"
+end
+
+local function wall_clock_ms()
+  local sec, usec = uv.gettimeofday()
+  return (sec * 1000) + math.floor(usec / 1000)
+end
+
+-- A watchdog escalation bypasses the CLI's Effect finalizers. Write the failed
+-- attempt synchronously while the child still owns `poll.lock`, so another
+-- editor cannot acquire the lock between SIGKILL and the shared rate bound.
+local function stamp_failed_attempt()
+  local fd = uv.fs_open(stamp_path(), "w", 384) -- 0600
+  if not fd then
+    return
+  end
+  uv.fs_write(fd, tostring(wall_clock_ms()), -1)
+  uv.fs_close(fd)
+end
+
+-- Whether some editor on this machine already reconciled within the interval.
+-- Read from the stamp's own mtime, so a torn or truncated write still carries a
+-- usable time and no parsing can fail here.
+local function polled_recently()
+  if not poll_interval_ms then
+    return false
+  end
+  local stat = uv.fs_stat(stamp_path())
+  if not stat then
+    return false
+  end
+  local stamped_at_ms = (stat.mtime.sec * 1000) + math.floor((stat.mtime.nsec or 0) / 1000000)
+  local age_ms = wall_clock_ms() - stamped_at_ms
+  -- A stamp dated in the future is a clock that moved backwards, not a poll that
+  -- has not happened yet; treating it as recent would wedge polling until the
+  -- clock caught up.
+  if age_ms < 0 then
+    return false
+  end
+  return age_ms < poll_interval_ms
+end
+
+local function own_pid()
+  if uv.os_getpid then
+    return uv.os_getpid()
+  end
+  return vim.fn.getpid()
+end
+
+-- One-shot scheduling keeps this editor's cadence anchored to completion, not
+-- start. A repeating timer would tick one interval after start, see the fresh
+-- completion stamp, skip, and wait a second whole interval before trying again.
+arm_poll = function(delay_ms)
+  if not poll_timer or not poll_config then
+    return
+  end
+  poll_timer:stop()
+  poll_timer:start(delay_ms, 0, vim.schedule_wrap(function()
+    poll_once(poll_config)
+  end))
+end
+
 -- Ask `job` to stop, then escalate if it does not. Signals the pid directly
 -- rather than calling `jobstop`, which starts nvim's own ~2s kill timer and
 -- would SIGKILL the CLI long before an in-flight OAuth rotation could finish.
 --
--- The guard is never released here: only proof of death releases it, because
--- letting a tick spawn a second poll beside a dying one is the stacking leak
--- this whole mechanism exists to prevent. When in doubt we keep holding, at the
--- cost of no further polling until nvim restarts.
+-- `flock --no-fork` execs the CLI, so the pid we signal is also the process
+-- holding the kernel lock. The lock cannot be released before that process is
+-- dead.
 local function terminate(job)
   local signalled, pid = pcall(vim.fn.jobpid, job)
   if signalled and pid > 0 then
     uv.kill(pid, "sigterm")
   else
+    stamp_failed_attempt()
     vim.fn.jobstop(job) -- no pid to signal; fall back to nvim's own teardown
   end
 
@@ -110,47 +243,73 @@ local function terminate(job)
     end
     if vim.fn.jobwait({ job }, 0)[1] ~= -1 then
       poll_job = nil -- already exited without `on_exit` reaching us
+      arm_poll(poll_interval_ms)
       return
     end
     -- SIGTERM was not enough. Escalate, and let `on_exit` do the releasing.
     local ok, live_pid = pcall(vim.fn.jobpid, job)
     if ok and live_pid > 0 then
+      stamp_failed_attempt()
       uv.kill(live_pid, "sigkill")
       return
     end
     -- No pid to escalate against, so nothing further will make this job report.
     -- `jobstop` once more, then release on the next proof rather than wedging
     -- the poll for the rest of the session.
+    stamp_failed_attempt()
     vim.fn.jobstop(job)
     vim.defer_fn(function()
       if poll_job == job and vim.fn.jobwait({ job }, 0)[1] ~= -1 then
         poll_job = nil
+        arm_poll(poll_interval_ms)
       end
     end, POLL_STOP_GRACE_MS)
   end, POLL_STOP_GRACE_MS)
 end
 
-local function poll_once(config)
+poll_once = function(config)
   if poll_job then
+    arm_poll(poll_interval_ms)
     return -- previous poll still in flight; do not stack
   end
-  if not M.read(config.state_path).active then
+  if not M.read(cli_state_path()).active then
+    arm_poll(poll_interval_ms)
     return -- no local timer, nothing to reconcile
   end
+  if polled_recently() then
+    arm_poll(poll_interval_ms)
+    return -- someone already reconciled this interval; read their result instead
+  end
 
   -- `job` is declared first so on_exit closes over it, not a global.
   local job
-  job = vim.fn.jobstart({ config.binary or "jcf", "timer", "status" }, {
+  job = vim.fn.jobstart({
+    "flock",
+    "--no-fork",
+    "--nonblock",
+    "--conflict-exit-code",
+    "75",
+    lock_path(),
+    config.binary or "jcf",
+    "timer",
+    "status",
+    "--nvim-poll-stamp",
+    stamp_path(),
+    "--nvim-poll-interval-ms",
+    tostring(poll_interval_ms),
+  }, {
     on_stdout = function() end,
     on_stderr = function() end,
     on_exit = function()
       if poll_job == job then
         poll_job = nil
+        arm_poll(poll_interval_ms)
       end
     end,
   })
   if job <= 0 then
-    return -- failed to spawn (missing binary); try again next tick
+    arm_poll(poll_interval_ms)
+    return -- failed to spawn (`flock` missing); try again next tick
   end
   poll_job = job
 
@@ -167,11 +326,26 @@ function M.start_poll(config, interval_ms)
     return
   end
   interval_ms = interval_ms or 30000 -- 30s default
+  if type(interval_ms) ~= "number" or interval_ms <= 0 or interval_ms % 1 ~= 0 then
+    return -- non-positive and non-integral values disable polling
+  end
+  poll_config = config
+  poll_interval_ms = interval_ms
+
+  -- Spread the first tick across a whole interval, keyed off the pid, so editors
+  -- opened in a batch (a session restore, a fleet of worktrees) do not line up on
+  -- the same millisecond forever after. Derived from the pid rather than
+  -- `math.random`, which is unseeded per process and would hand every editor the
+  -- same offset.
+  --
+  -- De-phasing is only safe because the stamp bounds the rate. Spreading the
+  -- ticks removes the collisions the lock would otherwise resolve, so with the
+  -- lock alone this would make things worse, not better: every tick would find
+  -- a free lock and spawn.
+  local first_ms = own_pid() % interval_ms
 
   poll_timer = uv.new_timer()
-  poll_timer:start(interval_ms, interval_ms, vim.schedule_wrap(function()
-    poll_once(config)
-  end))
+  arm_poll(first_ms)
 end
 
 function M.stop_poll()
@@ -180,6 +354,9 @@ function M.stop_poll()
     poll_timer:close()
     poll_timer = nil
   end
+  if not poll_job then
+    return
+  end
   if poll_job then
     -- Exactly the watchdog's sequence, for the same reason: `jobstop` here
     -- would hand the CLI nvim's ~2s kill timer and could SIGKILL it between the
@@ -187,6 +364,7 @@ function M.stop_poll()
     -- reconfiguration deserve the same grace as a timeout. (On `VimLeave` nvim
     -- exits before any of it elapses — the CLI's own retry-not-delete rule is
     -- what covers that case.)
+    stamp_failed_attempt()
     terminate(poll_job)
   end
 end

package/package.json

@@ -1,10 +1,25 @@
 {
   "name": "@knpkv/jira-clockify",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "description": "TUI for Jira-Clockify time tracking, attachable to neovim",
   "license": "MIT",
   "author": "knpkv",
   "type": "module",
+  "main": "dist/src/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./testing.js": {
+      "types": "./dist/src/testing/fakeHeadless.d.ts",
+      "default": "./dist/src/testing/fakeHeadless.js"
+    },
+    "./*.js": {
+      "types": "./dist/src/*.d.ts",
+      "default": "./dist/src/*.js"
+    }
+  },
   "bin": {
     "jcf": "dist/src/bin.js"
   },
@@ -18,30 +33,33 @@
     "skills"
   ],
   "dependencies": {
-    "@effect/atom-react": "4.0.0-rc.109",
-    "@effect/platform-node": "4.0.0-rc.109",
-    "@opentui/core": "0.5.1",
-    "@opentui/react": "0.5.1",
-    "effect": "4.0.0-rc.109",
-    "react": "^19.2.8",
-    "@knpkv/agent-skills": "^0.3.1",
-    "@knpkv/atlassian-common": "^1.4.1",
-    "@knpkv/clockify-api-client": "^1.1.1",
-    "@knpkv/jira-api-client": "^1.1.1",
-    "@knpkv/jira-cli": "^1.3.1"
+    "@effect/atom-react": "4.0.0",
+    "@effect/platform-node": "4.0.0",
+    "@opentui/core": "0.5.14",
+    "@opentui/react": "0.5.14",
+    "effect": "4.0.0",
+    "react": "^19.3.0",
+    "@knpkv/agent-skills": "^0.3.2",
+    "@knpkv/ai-claude": "^0.4.0",
+    "@knpkv/ai-codex": "^0.5.0",
+    "@knpkv/atlassian-common": "^1.5.0",
+    "@knpkv/clockify-api-client": "^2.0.0",
+    "@knpkv/jira-api-client": "^2.0.0",
+    "@knpkv/jira-cli": "^1.4.0"
   },
   "devDependencies": {
-    "@effect/vitest": "4.0.0-rc.109",
+    "@effect/vitest": "4.0.0",
     "@types/node": "latest",
-    "@types/react": "^19.2.18",
-    "tsx": "^4.23.12",
-    "vitest": "^4.1.10"
+    "@types/react": "^19.3.0",
+    "tsx": "^4.23.15",
+    "vitest": "^5.0.3"
   },
   "scripts": {
     "start": "tsx src/bin.ts",
     "build": "tsc -b && chmod +x dist/src/bin.js",
-    "check": "tsc -b tsconfig.json",
+    "check": "tsc -b tsconfig.json && tsc --noEmit -p test/tsconfig.json",
     "test": "vitest",
     "lint": "eslint \"{src,test}/**/*.{ts,tsx}\""
-  }
+  },
+  "types": "dist/src/index.d.ts"
 }

package/skills/jcf/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jcf
-description: Use the @knpkv/jira-clockify CLI to track work across Jira and Clockify. Trigger when the user asks an agent to start, stop, discard, edit, inspect, or manually log time for Jira tickets; configure Jira OAuth or Clockify API access; list current Jira tickets; set default Clockify project, billable flag, or JQL; or launch the jcf TUI.
+description: Use the @knpkv/jira-clockify CLI to track work across Jira and Clockify. Trigger when the user asks an agent to start, stop, discard, edit, inspect, or manually log time for Jira tickets; reconcile Clockify against Jira or recover forgotten time from local Claude Code and Codex sessions; configure Jira OAuth or Clockify API access; list current Jira tickets; set default Clockify project, billable flag, or JQL; or launch the jcf TUI.
 ---
 
 # Jcf
@@ -38,6 +38,15 @@ jcf config set jql 'assignee = currentUser() AND status != Done ORDER BY updated
 jcf config reset
 ```
 
+Configure which directories' Claude Code and Codex sessions may become proposed worklogs:
+
+```bash
+jcf config set session-root ~/dev/work
+jcf config set session-root ~/dev/work --remove
+jcf config set session-ticket ~/dev/work/docs PROJ-42
+jcf config set idle-cap 300
+```
+
 ## Timer Commands
 
 Launch the TUI:
@@ -85,6 +94,87 @@ Edit the running timer:
 jcf timer edit
 ```
 
+## Reconcile Commands
+
+Both forms are remote write commands: they create Clockify entries and Jira worklogs. Never run
+either unattended. Confirm the window and the direction (or the agent) with the user first, and
+prefer the read-only forms below when gathering information.
+
+Compare the two sides and fill whichever is short:
+
+```bash
+jcf sync reconcile clockify-to-jira --day
+jcf sync reconcile jira-to-clockify --week
+jcf sync reconcile clockify-to-jira --since 2026-07-01 --until 2026-07-07
+```
+
+Recover time neither side recorded, using local Claude Code and Codex sessions as evidence:
+
+```bash
+jcf sync reconcile --agent claude --day
+jcf sync reconcile --agent claude --week
+jcf sync reconcile --agent claude --json
+jcf sync reconcile --agent claude --day --calendar
+```
+
+- `--agent` is a mode switch, not a direction. Passing both is a usage error.
+- `claude` is the only supported agent mode; `--agent codex` fails. That mode reads in-scope Claude Code
+  and Codex sessions as evidence.
+- `--agent claude --json` is the read-only form: it writes exactly one JSON value to stdout, sends
+  everything human-facing to stderr, and creates no Clockify entry or Jira worklog. Use it to
+  inspect proposals before asking the user which to accept.
+- Without `--json`, every row needs an interactive confirmation, so this form is unsuitable for
+  unattended use.
+- Nothing is proposed for a directory outside the configured session roots, and a day with a timer
+  still running is reported but never proposed. Stop the timer and re-run to log that day.
+- Every picker row names the issue summary and assignee; `--json` carries both as `summary` and
+  `assignee`. Rows are not listed above the picker — the picker rows _are_ the report.
+- Written entries carry the issue title and an agent-written sentence saying what was done, read off
+  the session prompts. Notes are asked for only about confirmed rows, and only when writing, so
+  `--json` never spends a call on one. A row still writes when no note can be produced.
+- `--calendar` adds an ASCII hour-by-hour grid of when the time was credited. `--json` carries the
+  same information as a `blocks` array per proposal, with `startMs`, `endMs` and credited `seconds`,
+  plus the issue `summary`. Sum `seconds`, not wall-clock bounds, for shared work.
+- In `--json`, `ownershipWithheld` keeps rows assigned to someone else or unassigned, with a
+  `reason`; `withheld` remains the separate confidence-floor list. Neither list is offered to write.
+- `--json` and `--calendar` are agent-mode flags; passing either without `--agent` is a usage error.
+- Only messages the user typed count towards time; the agent's own output, its tool results, and
+  prompts it sends its own subagents do not, so an unattended agent run credits at most the idle cap
+  rather than the hour it ran for.
+- If Jira cannot be read, the run fails rather than proposing time that may already be logged.
+- Time worked on several issues at once is split equally between them, so a row's credited total can
+  be lower than the clock ranges beneath it; the report names the active total and the shared amount.
+- Each proposal shows the attribution signal behind it (`branch`, `path`, `standing`, `agent`).
+  A branch name states intent, not fact: time spent on an unrelated fix while on a ticket branch is
+  credited to that branch's ticket, so review the signal before confirming.
+
+## Watch Command
+
+```bash
+jcf watch claude              # Runs until interrupted; writes as work settles
+jcf watch claude --dry-run    # Prints what it would write, writes nothing
+jcf watch claude --interval 60
+```
+
+- A long-running remote write command. Only start it when the user explicitly asks for live
+  tracking, and say that it will keep writing until they stop it. Do not start it to answer a
+  question — it never terminates on its own, so it cannot be used to gather information.
+- `--dry-run` is the read-only form, but it still runs forever. To inspect unlogged work, use
+  `jcf sync reconcile --agent claude --json` instead.
+- It writes only branch-, path-, and standing-attributed blocks. Time only a coding agent could
+  place is reported and left for `jcf sync reconcile --agent claude`.
+- It writes a block once it has been quiet for one idle cap, so work in progress is never written.
+  Nothing is written twice _on this machine_ — a proposal is always the gap the two sides still have,
+  and the lease keeps a second local watch out. Two machines watching one Clockify account can still
+  duplicate: see ADR-0007.
+- It covers time since it started, plus any stretch a previous watch reached but had not written —
+  it leaves a cursor, so a restart resumes rather than dropping the block. A first run reaches back
+  for nothing. Earlier work in the same day needs `jcf sync reconcile`.
+- Only one watch writes at a time, per machine. Starting a second one prints who holds the lease and
+  exits; do not start one to "check" on a running watch. After an ungraceful process death, verify no
+  watch remains before manually removing `~/.jcf/watch.lease`; the file is never auto-taken-over.
+- It stops itself if Jira rejects the login. Re-authenticate with `jcf auth jira login` and restart.
+
 ## Agent Workflow
 
 1. Run `jcf auth status` and `jcf timer status` before changing timer state.
@@ -92,3 +182,5 @@ jcf timer edit
 3. Verify the active Jira profile when the user names a Jira site/account or before posting worklogs; `atlassian profiles doctor` shows Jira Clockify as a consumer of the `jira-cli` auth store.
 4. Prefer explicit flags for non-interactive work: issue key, duration, date, time, project id, billable flag, and comment.
 5. If no timer is running, `jcf timer stop` may offer an interactive correction interval; use `jcf timer log` for deterministic manual logging.
+6. To find unlogged work, read `jcf sync reconcile --agent claude --json` first and report the
+   proposals to the user; only they should decide which rows to write.