@workscribe/cli 2.1.0 → 3.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workscribe/cli",
-  "version": "2.1.0",
+  "version": "3.0.1",
   "description": "Passive developer work journal — automatic terminal activity summaries",
   "homepage": "https://workscribe.co",
   "repository": {

package/shell/hook.bash

@@ -1,9 +1,26 @@
 # Workscribe — developer work journal
 # Do not edit this block manually. Managed by `workscribe init`.
 # workscribe:hook:start
+# workscribe:hook-version 2
+# Now in milliseconds, or nothing: bash 5's $EPOCHREALTIME, else `date +%s` (macOS's bash 3.2 has no $EPOCHREALTIME,
+# and its BSD date has no %N)
+_workscribe_now_ms() {
+  if [[ -n "${EPOCHREALTIME:-}" ]]; then
+    local micros=${EPOCHREALTIME//[.,]/}
+    [[ $micros =~ ^[0-9]+$ ]] && echo $(( 10#$micros / 1000 ))
+    return 0
+  fi
+  local seconds
+  seconds=$(date +%s 2>/dev/null)
+  [[ $seconds =~ ^[0-9]+$ ]] && echo $(( seconds * 1000 ))
+  return 0
+}
+
 _workscribe_preexec() {
+  # The DEBUG trap also fires for the rest of the rc file — nothing before the first prompt is the user's command
+  [[ -n "${_workscribe_primed:-}" ]] || return 0
   if [ "$BASH_COMMAND" != "_workscribe_precmd" ]; then
-    _workscribe_cmd_start=$(date +%s%3N 2>/dev/null || echo 0)
+    _workscribe_cmd_start=$(_workscribe_now_ms)
     _workscribe_last_cmd="$BASH_COMMAND"
     _workscribe_git_before=$(git rev-parse HEAD 2>/dev/null || echo "")
   fi
@@ -13,17 +30,21 @@ _workscribe_precmd() {
   local exit_code=$?
   command -v workscribe &>/dev/null || return 0
   if [[ -n "$_workscribe_last_cmd" ]]; then
-    local now
-    now=$(date +%s%3N 2>/dev/null || echo 0)
-    local duration=$(( now - _workscribe_cmd_start ))
+    # The command is captured even when it can't be timed: no duration rather than no event
+    local now duration=""
+    now=$(_workscribe_now_ms)
+    if [[ $now =~ ^[0-9]+$ && $_workscribe_cmd_start =~ ^[0-9]+$ ]]; then
+      duration=$(( now - _workscribe_cmd_start ))
+    fi
     command workscribe _capture \
       --cmd "$_workscribe_last_cmd" \
       --cwd "$PWD" \
       --exit "$exit_code" \
-      --duration "$duration" \
+      ${duration:+--duration "$duration"} \
       ${_workscribe_git_before:+--git-before "$_workscribe_git_before"} \
       > /dev/null 2>&1 &
     _workscribe_last_cmd=""
+    _workscribe_cmd_start=""
     _workscribe_git_before=""
   fi
   # Skip the alert check on the first precmd: it fires before the shell has

package/shell/hook.zsh

@@ -1,6 +1,10 @@
 # Workscribe — developer work journal
 # Do not edit this block manually. Managed by `workscribe init`.
 # workscribe:hook:start
+# workscribe:hook-version 2
+# $EPOCHREALTIME exists only once zsh/datetime is loaded — plain zsh doesn't load it
+zmodload zsh/datetime 2>/dev/null
+
 _workscribe_preexec() {
   _workscribe_cmd_start=$EPOCHREALTIME
   _workscribe_cmd="$1"
@@ -11,16 +15,22 @@ _workscribe_precmd() {
   local exit_code=$?
   command -v workscribe > /dev/null 2>&1 || return 0
   if [[ -n "$_workscribe_cmd" ]]; then
-    local _raw_ms=$(( ($EPOCHREALTIME - $_workscribe_cmd_start) * 1000 ))
-    local duration_ms=${_raw_ms%%.*}
+    # Optional flags as an array: zsh doesn't word-split ${x:+--flag "$x"}, which would pass "--flag value" as one
+    # argument. And the command is captured even when it can't be timed.
+    local -a _workscribe_args
+    if [[ -n "$_workscribe_cmd_start" && -n "$EPOCHREALTIME" ]]; then
+      local _raw_ms=$(( (EPOCHREALTIME - _workscribe_cmd_start) * 1000 ))
+      _workscribe_args+=(--duration "${_raw_ms%%.*}")
+    fi
+    [[ -n "$_workscribe_git_before" ]] && _workscribe_args+=(--git-before "$_workscribe_git_before")
     command workscribe _capture \
       --cmd "$_workscribe_cmd" \
       --cwd "$PWD" \
       --exit "$exit_code" \
-      --duration "$duration_ms" \
-      ${_workscribe_git_before:+--git-before "$_workscribe_git_before"} \
+      "${_workscribe_args[@]}" \
       > /dev/null 2>&1 &!
     _workscribe_cmd=""
+    _workscribe_cmd_start=""
     _workscribe_git_before=""
   fi
   # Skip the alert check on the first precmd: it fires before the shell has

package/skills/workscribe/SKILL.md

@@ -22,18 +22,23 @@ workscribe sessions --json
 
 Add `--date YYYY-MM-DD` for another day. For "this week", run it once per day (Monday to today) and save each day's sessions — but note `workscribe summary --week` keeps using Workscribe's own digest; saved summaries are per day. The output is one line of JSON; see [references/json-contract.md](references/json-contract.md) for the fields you'll use. An empty `sessions` list means nothing was captured — tell the user and stop.
 
+Each session is one project's **thread** inside a work block. When the developer worked across several repos at once, their threads share a block and overlap in time: `alongside` lists the keys of the others.
+
+If it reports that **Workscribe hasn't finished upgrading the data**, ask the developer before running `workscribe upgrade` — it backs up their database first and can take a while on a long history. Once it finishes, run `workscribe sessions --json` again.
+
 ## 2. Write one block per session
 
 Follow [references/summary-format.md](references/summary-format.md). In short:
 
 ```
-## <project> (<branch>) — <duration>
+## <project> (<branches>) — <duration>
 - <outcome>
 ```
 
 - Up to **7 bullets**, most important first: what was built, fixed, shipped or decided.
 - Build bullets from `commits` (cite the short hash, e.g. `(a1b2c3d)`), test and build results (`exitCode` 0 vs non-zero; `null` means unknown, never "failed"), `notes` (always include them), and `hint`s on unclassified events.
 - Describe outcomes, not commands or tools. Never name the AI tool used. Don't invent anything the data doesn't show.
+- Don't name the projects worked `alongside` — Workscribe adds that line under each saved summary itself. Never repeat their work.
 - Skip a session with nothing notable rather than padding it.
 
 ## 3. Save each block
@@ -58,4 +63,4 @@ Show the summaries, then say they were saved to Workscribe: `workscribe summary`
 
 ## Privacy
 
-Running this skill sends the JSON — categories, commit subjects, notes, short redacted hints for unclassified commands, and each session's repo path and working directory; never full commands or IDE file paths — to the model provider behind this agent, along with any files you read under `repoPath`. If the developer needs summaries that never leave their machine, point them to `workscribe summary`, whose template engine runs entirely offline.
+Running this skill sends the JSON — categories, commit subjects, notes, short redacted hints for unclassified commands, the ids of the agent conversations the work came from, and each session's repo path and working directory; never full commands or IDE file paths — to the model provider behind this agent, along with any files you read under `repoPath`. If the developer needs summaries that never leave their machine, point them to `workscribe summary`, whose template engine runs entirely offline.

package/skills/workscribe/references/json-contract.md

@@ -1,24 +1,39 @@
 # `workscribe sessions --json` — fields this skill uses
 
-The full contract is documented at workscribe.co/docs/commands#json-output-contract. Within `schemaVersion: 1`, fields are only ever added — ignore any you don't recognise.
+The full contract is documented at workscribe.co/docs/commands#json-output-contract. Within `schemaVersion: 2`, fields are only ever added — ignore any you don't recognise.
+
+Each session is one project's **thread**: that project's work inside a work block (a stretch between idle gaps). Working across several repos at once gives one block with a thread per repo, so sessions of one block overlap in time.
 
 ```json
 {
-  "schemaVersion": 1,
+  "schemaVersion": 2,
   "date": "2026-10-25",
+  "blocks": [
+    {
+      "id": 1,
+      "startedAt": "2026-10-25T09:00:00.000Z",
+      "endedAt": "2026-10-25T10:30:00.000Z",
+      "activeMinutes": 85,
+      "threadKeys": ["api|2026-10-25T09:00:00.000Z", "web|2026-10-25T09:40:00.000Z"]
+    }
+  ],
   "sessions": [
     {
       "key": "api|2026-10-25T09:00:00.000Z",
       "project": "api",
       "repoPath": "/Users/dev/api",
       "branch": "feature/auth",
+      "branches": ["feature/auth", "main"],
       "startedAt": "2026-10-25T09:00:00.000Z",
       "endedAt": "2026-10-25T10:30:00.000Z",
-      "durationMinutes": 90,
+      "activeMinutes": 70,
+      "blockId": 1,
+      "alongside": ["web|2026-10-25T09:40:00.000Z"],
+      "tickets": ["API-412"],
       "notes": ["blocked on staging credentials"],
       "commits": [
-        { "hash": "a1b2c3d", "subject": "fix: token refresh race", "source": "git" },
-        { "hash": null, "subject": "wip: amended away", "source": "captured" }
+        { "hash": "a1b2c3d", "subject": "fix: token refresh race", "committedAt": "2026-10-25T10:12:00+01:00", "source": "git" },
+        { "hash": null, "subject": "wip: amended away", "committedAt": "2026-10-25T09:41:07.000Z", "source": "captured" }
       ],
       "events": [
         { "category": "testing", "exitCode": 1, "metadata": { "tool": "npm" } },
@@ -33,7 +48,10 @@ The full contract is documented at workscribe.co/docs/commands#json-output-contr
 | Field | Use it for |
 |---|---|
 | `key` | The `--key` when saving this session's summary. Copy it exactly. |
-| `project`, `branch`, `durationMinutes` | The block heading. `project` is the repo name, a `~/path` for work outside git, or `null` (write `unknown`). |
+| `project`, `branch`, `activeMinutes` | The block heading. `project` is the project's name, a `~/path` for work outside any project, or `null` (write `unknown`). `activeMinutes` is the time spent on this project; `startedAt`–`endedAt` can span other projects' work too. |
+| `branches` | Every branch the session touched, in the order first seen. `branch` is the latest of them, the one the session ended on. Each commit's `committedAt` says when it was made. |
+| `alongside` | The keys of the sessions worked in the same block. Don't mention those projects — Workscribe adds an `Alongside:` line under each summary itself — and leave their work to their own blocks. |
+| `tickets` | Ticket keys the session's branches and commits name. Mention one when the work is about it (e.g. "Fixed the token refresh race (API-412)"); don't list them for their own sake. May be empty even when a branch names one, right after an update. |
 | `repoPath` | Where to read files if a commit needs context. `null` outside a git repo. |
 | `notes` | The developer's own notes — always include them. |
 | `commits` | The main source of outcomes. `source: "git"` has a short `hash` to cite; `"captured"` commits have `hash: null` (amended or rebased). |

package/skills/workscribe/references/summary-format.md

@@ -5,12 +5,13 @@ One block per session, in exactly the shape Workscribe uses everywhere else, so
 ## Heading
 
 ```
-## <project> (<branch>) — <duration>
+## <project> (<branches>) — <duration>
 ```
 
-- Leave out ` (<branch>)` when `branch` is `null`.
+- `<branches>` is every branch in `branches`, in order, separated by `, ` — for example `## api (main, feature/auth) — 1h 30m`. With one branch it's just that branch.
+- Leave out the parentheses when `branches` is empty.
 - If `project` is `null` (no repo and no events), use `unknown`, as Workscribe does.
-- Duration from `durationMinutes`: under an hour as `45m`; otherwise `1h` or `1h 30m`.
+- Duration from `activeMinutes` — the time actually spent on that project; a session's start-to-end span can include work on other projects. Under an hour as `45m`; otherwise `1h` or `1h 30m`.
 
 ## Bullets