@erclx/aitk 3.51.1 → 3.52.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "3.51.1",
+  "version": "3.52.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/claude-orchestrate/scripts/watch.sh

@@ -5,7 +5,12 @@
 # holds. This answers "what just changed" on a loop of its own, and it exists
 # because the two readings a dispatch needs are not one reading: a worker that
 # finishes goes idle and a worker that crashes vanishes, so a watch matching
-# only the pull request list stays silent through the second.
+# only the pull request list stays silent through the second. A third case is
+# neither: a worker that stops on a question or a prompt neither finishes nor
+# crashes, and sits reading "waiting" beside the two statuses that resolve on
+# their own until something reports it, which is the WORKER-STOPPED line
+# below, or WORKER-UNMEASURABLE for a "waiting" row too old to carry a stamp
+# this reads.
 #
 # `set -e` is deliberately not set. This runs for hours, and one transient `gh`
 # failure aborting the loop is a silent stop rather than a reported one. Every
@@ -17,6 +22,28 @@ set -uo pipefail
 # in a project whose workers run long.
 INTERVAL=60
 
+# Seconds a worker can sit in "waiting" before this reports it as stopped
+# rather than folding it into the ordinary status-change lines below. "busy"
+# and "idle" resolve on their own; "waiting" does not, so a dwell that keeps
+# growing there is a session blocked on something outside itself.
+#
+# Measured against the live session registry: 341 usable records carried a
+# status at all, and exactly one carried "waiting", too sparse a sample to fit
+# a distribution. The number is picked from the two bounds the measurement can
+# still name rather than from a round guess: well above INTERVAL, so a handful
+# of passes confirm the row before it reports rather than one slow tool call
+# tripping it, and well inside the ten-to-thirty-minute span a dispatched build
+# ordinarily runs, so a real stall is caught with most of that window still
+# open to act on it.
+#
+# That one record carried `waitingFor: "approve Bash"`, a permission prompt
+# rather than a question, and the two clear on different schedules: a prompt
+# resolves the moment a person approves it, where a question can sit
+# legitimately while a controller finishes a turn. This number is defensible
+# for the second and generous for the first, and the gap stays open rather
+# than splitting the constant on a sample of one.
+STALL_THRESHOLD_S=300
+
 # Resolving the main worktree root rather than this file's folder keeps a watch
 # started from a linked worktree reading the same repository as one started from
 # main. The repository field on a roster row is that root's `.git`.
@@ -40,13 +67,19 @@ BASE_BRANCH="${BASE_REF#origin/}"
 # worker, whoever launched it. The prototype matched the `orchestrator-` prefix
 # instead, which reads a dispatched worker and misses every hand-launched one,
 # and those are the ordinary shape whenever the operator is launching.
+#
+# The row goes out tab-separated and comes back read with IFS set to a tab. A
+# name this client actually writes carries spaces, `Update session markdown
+# and check runnable commands (3)` among them, and splitting on whitespace
+# took that one apart into a wrong name, branch, status, and dwell.
 read_workers() {
   aitk sessions list --json 2>/dev/null | tail -1 | jq -r \
     --arg repository "$REPOSITORY" --arg base "$BASE_BRANCH" '
       .sessions[]?
       | select(.repository == $repository)
       | select(.branch != null and .branch != $base)
-      | "\(.name) \(.branch) \(.status)"
+      | [.name, .branch, .status, (.statusDwellMs // -1 | tostring)]
+      | @tsv
     ' 2>/dev/null | sort
 }
 
@@ -70,6 +103,15 @@ prev_names=""
 pulls_seen=0
 workers_seen=0
 
+# One row per worker name currently reported, waiting past STALL_THRESHOLD_S
+# or waiting with no stamp to measure, so a reader watching the log is told
+# once rather than on every remaining pass. The prototype for that shape is
+# the WORKER-GONE/WORKER pair above, tracked in the same state a status change
+# is: a name drops out the pass it stops reading "waiting", which lets the
+# same worker report a second stall later in its life rather than being
+# marked forever by its first one.
+declare -A stalled
+
 while true; do
   pulls="$(read_pulls)"
   pulls_read=$?
@@ -83,7 +125,7 @@ while true; do
     echo "watch: the session roster failed to load, so no worker is classified this pass"
   fi
 
-  names="$(printf '%s\n' "$workers" | awk 'NF {print $1}' | sort -u)"
+  names="$(printf '%s\n' "$workers" | awk -F'\t' 'NF {print $1}' | sort -u)"
 
   if [ "$pulls_seen" -eq 1 ] && [ "$pulls_read" -eq 0 ]; then
     comm -13 <(printf '%s\n' "$prev_pulls") <(printf '%s\n' "$pulls") | grep . || true
@@ -96,6 +138,35 @@ while true; do
       grep . | sed 's/^/WORKER-GONE /' || true
   fi
 
+  if [ "$workers_read" -eq 0 ]; then
+    while IFS=$'\t' read -r w_name w_branch w_status w_dwell_ms; do
+      [ -z "$w_name" ] && continue
+
+      if [ "$w_status" != "waiting" ]; then
+        unset "stalled[$w_name]"
+        continue
+      fi
+
+      if [ "$w_dwell_ms" = "-1" ]; then
+        if [ -z "${stalled[$w_name]:-}" ]; then
+          echo "WORKER-UNMEASURABLE $w_name $w_branch"
+          stalled[$w_name]=1
+        fi
+        continue
+      fi
+
+      w_dwell_s=$((w_dwell_ms / 1000))
+      if [ "$w_dwell_s" -ge "$STALL_THRESHOLD_S" ]; then
+        if [ -z "${stalled[$w_name]:-}" ]; then
+          echo "WORKER-STOPPED $w_name $w_branch ${w_dwell_s}s"
+          stalled[$w_name]=1
+        fi
+      else
+        unset "stalled[$w_name]"
+      fi
+    done <<<"$workers"
+  fi
+
   if [ "$pulls_read" -eq 0 ]; then
     prev_pulls="$pulls"
     pulls_seen=1

package/docs/agents/sessions.md

@@ -105,6 +105,14 @@ Every report states how liveness was decided, on a pass as well as a failure.
 
 The registry holds one record per session and is never pruned, so it accumulates thousands of entries. On the `unverified` path a stale record whose pid has been reused reads as live, which is why the field is reported rather than assumed.
 
+## The status dwell
+
+Every row carries `statusUpdatedAt`, the stamp a client writes beside `status` at the moment it last changed, and `statusDwellMs`, the elapsed milliseconds since that stamp. Measured over the live registry, 23 of 341 usable records carry `statusUpdatedAt`, so `null` is the ordinary answer rather than an edge case, and the absence tracks a client version rather than a record's age alone: the one record ever measured carrying `status: "waiting"` is among the 318 without it.
+
+`statusDwellMs` falls back to the coarser `updatedAt` stamp when `statusUpdatedAt` is absent, so it is `null` only where a record carries neither. `statusUpdatedAt` itself is never backfilled from the fallback and stays `null` in that case, since it names the exact stamp rather than an estimate. A stamp ahead of the reading clock clamps the dwell to zero rather than reporting a negative one.
+
+The dwell is what separates a status that resolves on its own from one that does not. `busy` and `idle` transition without help, so a long dwell there is ordinary. `waiting` does not: a session in that state is blocked on something outside itself, and a dwell that keeps growing past the ordinary span of a prompt is a session stalled rather than paused. `aitk sessions list` renders the dwell beside the status at the coarsest unit that keeps it a whole number, and the JSON record carries both fields on every row.
+
 ## What the read depends on
 
 The records live under the Claude Code configuration directory, which the verb resolves from `CLAUDE_CONFIG_DIR` and falls back to `~/.claude`. Their location, their filenames, and the fields inside them are a client implementation detail rather than a published interface, so a client change can move them. The verb reports an absent registry as a refusal rather than as a machine running no sessions, which is what surfaces the move instead of burying it in an empty roster.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "3.51.1",
+  "version": "3.52.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/commands/sessions.ts

@@ -124,6 +124,14 @@ export function register(program: Command): void {
         'cannot rule out a pid handed to an unrelated process, so a roster',
         'reported that way is a candidate list rather than an identity.',
         '',
+        'The JSON record also carries "statusUpdatedAt" (the stamp the client',
+        'wrote beside "status", or null where its record carries none) and',
+        '"statusDwellMs" (the elapsed milliseconds since that stamp, falling',
+        'back to the coarser "updatedAt" where the narrower one is absent,',
+        'computed at read time and clamped at zero against clock skew). The',
+        'framed listing renders the same dwell beside the status, at the',
+        'coarsest unit that keeps it a whole number.',
+        '',
         'Examples:',
         '  aitk sessions list',
         '  aitk sessions list --json',
@@ -349,12 +357,30 @@ function reportSessions(
         const held =
           session.branch ??
           `unresolved: ${REASONS[session.unresolved ?? ''] ?? 'unknown'}`
-        return `${session.name}  ${session.status}  ${held}\n  ${session.cwd}`
+        const dwell = formatDwell(session.statusDwellMs)
+        const status = dwell ? `${session.status} ${dwell}` : session.status
+        return `${session.name}  ${status}  ${held}\n  ${session.cwd}`
       })
       .join('\n'),
   )
 }
 
+/**
+ * Renders the dwell at the coarsest unit that keeps it a whole number, since a
+ * reader scanning a roster wants an age at a glance rather than a millisecond
+ * count. An absent dwell renders as nothing, folding a status carrying no
+ * stamp back to the bare status line the reader already knew.
+ */
+function formatDwell(ms: number | null): string {
+  if (ms === null) return ''
+  const seconds = Math.round(ms / 1000)
+  if (seconds < 60) return `${seconds}s`
+  const minutes = Math.round(seconds / 60)
+  if (minutes < 60) return `${minutes}m`
+  const hours = Math.round(minutes / 60)
+  return `${hours}h`
+}
+
 function reportClaim(claim: ClaimReport): void {
   logStep('Claim')
 

package/src/sessions/registry.ts

@@ -21,6 +21,23 @@ export interface SessionRecord {
   readonly sessionId: string | undefined
   readonly kind: string | undefined
   readonly status: string | undefined
+  /**
+   * The epoch millisecond the client last changed `status`. Measured against
+   * the live registry, 23 of 341 usable records carry it, and the one record
+   * that has ever carried `status: "waiting"` is not among them, so its
+   * absence tracks a client version rather than a record's age alone.
+   * Declared here rather than read opportunistically off the parsed object,
+   * since this file is what states what the domain reads and an undeclared
+   * field read anyway is the drift this domain exists downstream of.
+   */
+  readonly statusUpdatedAt: number | undefined
+  /**
+   * The epoch millisecond the client last wrote the record at all, a coarser
+   * stamp than `statusUpdatedAt` that a client writes whether or not it also
+   * stamps the status change itself. Declared as the fallback dwell source
+   * for a record predating the narrower field, per the same reasoning above.
+   */
+  readonly updatedAt: number | undefined
   readonly startedAt: number | undefined
   /**
    * The process start time the client stamped at launch, compared against the

package/src/sessions/resolve.ts

@@ -23,6 +23,25 @@ export interface ResolvedSession {
   readonly kind: string
   readonly status: string
   readonly startedAt: string | null
+  /**
+   * The stamp the record carries beside `status`, kept alongside the dwell it
+   * computes below for a caller comparing two sessions rather than reading the
+   * age of one.
+   */
+  readonly statusUpdatedAt: string | null
+  /**
+   * Elapsed milliseconds since `statusUpdatedAt`, falling back to the coarser
+   * `updatedAt` when the record predates the narrower field, computed once at
+   * read time so three callers do not each convert the raw stamp and each get
+   * the clock-skew case wrong. The one record ever measured carrying
+   * `status: "waiting"` has exactly this shape: no `statusUpdatedAt`, an
+   * `updatedAt` beside it, so a caller reading this field alone would report
+   * the single real instance as unmeasured rather than as stalled.
+   * Clamped at zero rather than reported negative: a record stamped
+   * by a clock running ahead of this one is a skew to absorb, not a session
+   * that has not started waiting yet.
+   */
+  readonly statusDwellMs: number | null
   /**
    * The shared git directory every worktree of one repository resolves to,
    * which is what identifies the repository a row belongs to. A branch name is
@@ -52,6 +71,8 @@ export interface ResolveOptions {
   readonly dir?: string
   readonly probes?: LivenessProbes
   readonly locate?: (cwd: string) => Promise<Located>
+  /** The instant the dwell is computed against. Defaults to `Date.now`. */
+  readonly now?: () => number
 }
 
 export interface Located {
@@ -123,6 +144,17 @@ export async function repositoryOf(cwd: string): Promise<string | null> {
   return resolved.length > 0 ? resolved : null
 }
 
+/**
+ * Falls back to `updatedAt` when `statusUpdatedAt` is absent, since the
+ * narrower field is the newer of the two and a record predating it still
+ * carries the coarser one. The one record measured with `status: "waiting"`
+ * takes exactly this path: no `statusUpdatedAt`, an `updatedAt` beside it.
+ */
+function dwellMs(record: SessionRecord, now: number): number | null {
+  const stamp = record.statusUpdatedAt ?? record.updatedAt
+  return stamp === undefined ? null : Math.max(0, now - stamp)
+}
+
 /**
  * An absent field is rendered as an absence rather than as a value.
  *
@@ -131,7 +163,11 @@ export async function repositoryOf(cwd: string): Promise<string | null> {
  * for data. Null says the record did not carry it, which is the same
  * distinction the registry draws between an absent folder and an empty one.
  */
-function present(record: SessionRecord, located: Located): ResolvedSession {
+function present(
+  record: SessionRecord,
+  located: Located,
+  now: number,
+): ResolvedSession {
   return {
     name: record.name,
     pid: record.pid,
@@ -143,6 +179,11 @@ function present(record: SessionRecord, located: Located): ResolvedSession {
       record.startedAt === undefined
         ? null
         : new Date(record.startedAt).toISOString(),
+    statusUpdatedAt:
+      record.statusUpdatedAt === undefined
+        ? null
+        : new Date(record.statusUpdatedAt).toISOString(),
+    statusDwellMs: dwellMs(record, now),
     repository: located.repository,
     worktree: located.worktree,
     branch: located.branch,
@@ -167,6 +208,7 @@ export async function resolveSessions(
 ): Promise<SessionReport> {
   const probes = opts.probes ?? SYSTEM_PROBES
   const find = opts.locate ?? locate
+  const now = opts.now?.() ?? Date.now()
   const registry = readRegistry(opts.dir)
 
   if (registry.kind === 'absent') return { kind: 'absent', dir: registry.dir }
@@ -182,7 +224,7 @@ export async function resolveSessions(
   }
 
   const sessions = await Promise.all(
-    live.map(async (record) => present(record, await find(record.cwd))),
+    live.map(async (record) => present(record, await find(record.cwd), now)),
   )
 
   return { kind: 'resolved', dir: registry.dir, confidence, sessions }