rvlib-shipkit 2.1.1 → 2.3.0

package/src/agent-time/timeline.ts

@@ -0,0 +1,218 @@
+// The time math of one transcript stream (a session, or one sub-agent run):
+// how long each tool call took, and where the wall time went.
+//
+// The constraint a reader breaks first: parallel calls overlap. A call's own
+// time is end minus start, and a sum of those is CALL time, which can exceed
+// the wall. The wall is cut once, by a sweep over every boundary, so a second
+// of wall lands in exactly one bucket.
+import type { Outcome } from '../reflect/transcript.ts'
+
+export type Call = {
+    id: string
+    start: number
+    /** null while its result has not arrived (a live call, or one never answered) */
+    end: number | null
+    tool: string
+    shape: string
+    cmd: string
+    outcome: Outcome | null
+    code: number | null
+    /** it waited for the human to allow it */
+    approval: boolean
+    /** how it was allowed (transcript.ts Perm) */
+    perm: string
+    /** it only read (turns.ts isReadOnly, judged when indexed) */
+    read: boolean
+}
+
+export type Mark = { at: number; kind: 'prompt' | 'wake' | 'message' | 'reply' }
+
+export type Stream = { calls: Call[]; marks: Mark[] }
+
+/** where a slice of wall time went */
+export type Bucket = 'model' | 'tools' | 'approval' | 'subagent' | 'background' | 'human' | 'idle'
+
+export type Breakdown = Record<Bucket, number>
+
+/** a wait on him longer than this is the session parked, not a wait */
+export const IDLE_MS = 30 * 60 * 1000
+
+export const emptyBreakdown = (): Breakdown => ({ model: 0, tools: 0, approval: 0, subagent: 0, background: 0, human: 0, idle: 0 })
+
+/** a foreground sub-agent call: the session waits on another agent's work */
+export const isAgentCall = (c: Call): boolean => c.tool === 'Agent' || c.tool === 'Task'
+
+/** the first value of a sorted list above `t`, by bisection */
+function firstAfter(sorted: number[], t: number): number | undefined {
+    let lo = 0
+    let hi = sorted.length
+    while (lo < hi) {
+        const mid = (lo + hi) >> 1
+        if ((sorted[mid] as number) <= t) lo = mid + 1
+        else hi = mid
+    }
+    return sorted[lo]
+}
+
+/** the end every call is measured to: its result, else the next prompt or wake
+ *  after it (the human moved on, so it was interrupted), else the stream's last
+ *  event. `open` says the end was inferred */
+export type Closed = Call & { stop: number; open: boolean }
+
+/** sorted by start */
+export function closeCalls(s: Stream): Closed[] {
+    const turns = s.marks.filter((m) => m.kind !== 'reply').map((m) => m.at).sort((a, b) => a - b)
+    let last = 0
+    for (const m of s.marks) if (m.at > last) last = m.at
+    for (const c of s.calls) if ((c.end ?? c.start) > last) last = c.end ?? c.start
+    return s.calls
+        .map((c): Closed => {
+            if (c.end != null) return { ...c, stop: Math.max(c.start, c.end), open: false }
+            const next = firstAfter(turns, c.start)
+            return { ...c, stop: next ?? last, open: true }
+        })
+        .sort((a, b) => a.start - b.start)
+}
+
+/** the call's own duration in ms */
+export const callMs = (c: { start: number; stop: number }): number => Math.max(0, c.stop - c.start)
+
+type Point = { at: number; d: 'start' | 'stop' | Mark['kind']; lane: 'tool' | 'agent' | 'approval'; ix: number }
+
+/** the wall of one stream cut into buckets, clipped to [from, to]. Between two
+ *  boundaries: a tool in flight → tools; only calls waiting for his allow →
+ *  approval; only a sub-agent in flight → subagent;
+ *  nothing in flight and the next thing is his prompt → human (idle past
+ *  IDLE_MS); the next thing is a wake (a task notification, a hand-back) →
+ *  background; a message relayed in counts as a prompt (a sub-agent that
+ *  handed back sits parked until the coordinator or he writes to it); anything else → the model was working.
+ *
+ *  `turnModel` (one slot per closed call) receives the model stretch that
+ *  ended in each call: the turn that issued it, split evenly over the calls
+ *  of one batch. A stretch that ends in his prompt or a wake was the final
+ *  reply and goes to no call */
+export function wallBreakdown(s: Stream, from = -Infinity, to = Infinity, idleMs = IDLE_MS, closed: Closed[] = closeCalls(s), turnModel?: Float64Array): Breakdown {
+    const out = emptyBreakdown()
+    const points: Point[] = []
+    closed.forEach((c, ix) => {
+        const lane = isAgentCall(c) ? 'agent' : c.approval ? 'approval' : 'tool'
+        points.push({ at: c.start, d: 'start', lane, ix }, { at: c.stop, d: 'stop', lane, ix })
+    })
+    for (const m of s.marks) points.push({ at: m.at, d: m.kind, lane: 'tool', ix: -1 })
+    points.sort((a, b) => a.at - b.at)
+    let tools = 0
+    let agents = 0
+    let approvals = 0
+    let pending = 0
+    const issued: number[] = []
+    let i = 0
+    while (i < points.length) {
+        const at = (points[i] as Point).at
+        issued.length = 0
+        let ended = false
+        while (i < points.length && (points[i] as Point).at === at) {
+            const p = points[i] as Point
+            const n = p.d === 'start' ? 1 : p.d === 'stop' ? -1 : 0
+            if (p.lane === 'agent') agents += n
+            else if (p.lane === 'approval') approvals += n
+            else tools += n
+            if (p.d === 'start') issued.push(p.ix)
+            else if (p.d === 'prompt' || p.d === 'wake' || p.d === 'message') ended = true
+            i++
+        }
+        if (turnModel != null) {
+            if (issued.length > 0) for (const ix of issued) turnModel[ix] = (turnModel[ix] ?? 0) + pending / issued.length
+            if (issued.length > 0 || ended) pending = 0
+        }
+        if (i >= points.length) break
+        const nextAt = (points[i] as Point).at
+        const a = Math.max(at, from)
+        const b = Math.min(nextAt, to)
+        if (b <= a) continue
+        const len = b - a
+        let bucket: Bucket
+        if (tools > 0) bucket = 'tools'
+        else if (approvals > 0) bucket = 'approval'
+        else if (agents > 0) bucket = 'subagent'
+        else {
+            let next = i
+            let prompt = false
+            let wake = false
+            while (next < points.length && (points[next] as Point).at === nextAt) {
+                const d = (points[next] as Point).d
+                if (d === 'prompt' || d === 'message') prompt = true
+                if (d === 'wake') wake = true
+                next++
+            }
+            const gap = nextAt - at
+            bucket = prompt ? (gap > idleMs ? 'idle' : 'human') : wake ? 'background' : 'model'
+        }
+        out[bucket] += len
+        if (bucket === 'model') pending += len
+    }
+    return out
+}
+
+export const addBreakdown = (into: Breakdown, b: Breakdown): Breakdown => {
+    for (const k of Object.keys(into) as Bucket[]) into[k] += b[k]
+    return into
+}
+
+/** a failed call is retried when the next call of the same shape in the
+ *  stream comes within this window */
+export const RETRY_MS = 10 * 60 * 1000
+
+export const FAILED: ReadonlySet<Outcome> = new Set<Outcome>(['exit', 'error', 'timeout'])
+
+export type Retry = { failed: Closed; next: Closed; blind: boolean }
+
+/** every failed call followed by the same shape again: `blind` when the
+ *  command is the exact same text, so nothing changed between the two.
+ *  `calls` sorted by start (closeCalls) */
+export function retries(calls: Closed[]): Retry[] {
+    const out: Retry[] = []
+    const nextOfShape = new Map<string, Closed>()
+    for (let i = calls.length - 1; i >= 0; i--) {
+        const c = calls[i] as Closed
+        const next = nextOfShape.get(c.shape)
+        nextOfShape.set(c.shape, c)
+        if (c.outcome == null || !FAILED.has(c.outcome)) continue
+        if (next == null || next.start - c.stop > RETRY_MS) continue
+        out.push({ failed: c, next, blind: next.cmd.trim() === c.cmd.trim() })
+    }
+    return out.reverse()
+}
+
+/** a call that ran longer than this before a complaint is not looked for */
+const LOOKBACK_MS = 3 * 60 * 60 * 1000
+
+/** what the agent ran in the minutes before `at`: calls in flight at that
+ *  moment or started in the window, cut at `at`, longest first. `calls`
+ *  sorted by start (closeCalls) */
+export function ranBefore(calls: Closed[], at: number, windowMs = 10 * 60 * 1000): Closed[] {
+    let lo = 0
+    let hi = calls.length
+    while (lo < hi) {
+        const mid = (lo + hi) >> 1
+        if ((calls[mid] as Closed).start <= at) lo = mid + 1
+        else hi = mid
+    }
+    const out: Closed[] = []
+    for (let i = lo - 1; i >= 0; i--) {
+        const c = calls[i] as Closed
+        if (c.start < at - LOOKBACK_MS) break
+        if (c.stop >= at - windowMs) out.push({ ...c, stop: Math.min(c.stop, at) })
+    }
+    return out.sort((a, b) => callMs(b) - callMs(a))
+}
+
+/** p in [0, 1] of a list of ms, nearest rank */
+export function quantile(xs: number[], p: number): number {
+    return quantileSorted([...xs].sort((a, b) => a - b), p)
+}
+
+/** the same over a list already sorted ascending */
+export function quantileSorted(s: number[], p: number): number {
+    if (s.length === 0) return 0
+    return s[Math.min(s.length - 1, Math.max(0, Math.ceil(p * s.length) - 1))] ?? 0
+}

package/src/agent-time/turns.ts

@@ -0,0 +1,135 @@
+// Turn count: what makes an agent slow when no command is. Every tool call
+// costs a model turn before it, so an agent that reads one file per turn
+// spends its wall on the model, not on the reads. The two questions this
+// module answers on pure data: was a call a single read, and did it go out in
+// parallel with the one before it.
+//
+// The constraint a reader breaks first: a read is judged on the WHOLE command,
+// never on its shape alone. `grep -l x | xargs sed -i` shapes as `grep`, and
+// it writes.
+import { stripHeredocs } from './shape.ts'
+import type { Closed } from './timeline.ts'
+
+/** bumped with any read rule below: the index judges every stored call again */
+export const READ_VERSION = 1
+
+/** tools that only read */
+export const READ_TOOLS: ReadonlySet<string> = new Set(['Read', 'Grep', 'Glob'])
+
+/** Bash shapes that only read (shape.ts names them). `sed` without `-i` prints;
+ *  `sed -i` is shaped `sed -i (edit)` and `cat > f` is `cat > (write)`, so
+ *  neither is here */
+export const READ_SHAPES: ReadonlySet<string> = new Set(['grep', 'rg', 'git grep', 'sed', 'cat', 'ls', 'head', 'tail', 'wc', 'find', 'git status', 'git log', 'git diff', 'git show'])
+
+/** words a read command may carry beside its read: scene setting, loop and
+ *  test words, a filter it pipes into, a print */
+const BESIDE = new Set([
+    'cd', 'pushd', 'popd', 'export', 'set', 'true', ':', 'time', 'for', 'do', 'done', 'while', 'if', 'then', 'else', 'fi', '[', '[[', 'test',
+    'echo', 'printf', 'pwd', 'uptime', 'date', 'which', 'basename', 'dirname', 'realpath', 'stat', 'file', 'du', 'tree', 'diff',
+    'sort', 'uniq', 'cut', 'tr', 'nl', 'column', 'jq', 'awk', 'xargs', 'grep', 'egrep', 'rg', 'head', 'tail', 'wc', 'cat', 'sed', 'ls', 'find', 'git',
+])
+
+/** a find action that writes or runs something */
+const FIND_ACTS = /\s-(?:delete|exec|execdir|ok|okdir|fprint0?|fprintf|fls)\b/
+
+/** git subcommands that only read */
+const GIT_READS = new Set(['status', 'log', 'diff', 'show', 'grep', 'ls-files', 'ls-tree', 'rev-parse', 'rev-list', 'merge-base', 'cat-file', 'describe', 'shortlog', 'branch', 'blame'])
+
+/** the parts of a command line: statements and every pipeline part, quoted
+ *  text blanked (a pattern is never a separator nor a redirect) */
+const parts = (command: string): string[] =>
+    (command.includes('<<') ? stripHeredocs(command) : command)
+        .replace(/\\\n/g, ' ')
+        .replace(/'[^']*'|"(?:[^"\\]|\\.)*"/g, '""')
+        .split(/&&|\|\||[;\n|]|(?<![>&])&(?![>&])/)
+
+/** an output redirect to a file: `> f`, `>> f`, `&> f`; `2>&1` and
+ *  `> /dev/null` write nothing */
+const writesFile = (part: string): boolean => {
+    for (const m of part.matchAll(/>{1,2}\s*([^\s>]*)/g)) {
+        const target = m[1] ?? ''
+        if (target === '' || target.startsWith('&') || target === '/dev/null' || target.startsWith('/dev/std')) continue
+        return true
+    }
+    return false
+}
+
+/** the words of a part after env assignments and a leading `X=$(` */
+const HEAD = /^[\s(]*(?:[A-Za-z_][A-Za-z0-9_]*=(?:\$\(|\S*\s+))*(\S+)\s*(.*)$/s
+
+/** one part of the line reads only */
+function partReads(part: string, whole: string): boolean {
+    if (writesFile(part)) return false
+    if (/^\s*[A-Za-z_][A-Za-z0-9_]*=\S*\s*$/.test(part)) return true
+    const m = HEAD.exec(part)
+    if (m == null) return true
+    const head = (m[1] as string).replace(/^.*\//, '').replace(/\)+$/, '')
+    const rest = ` ${m[2] ?? ''}`
+    if (!BESIDE.has(head)) return false
+    if (head === 'sed') return !/\s-[a-zA-Z]*i|\s--in-place/.test(rest)
+    if (head === 'find') return !FIND_ACTS.test(rest)
+    if (head === 'awk') return !/system\(|print[^;'"]*>/.test(whole)
+    if (head === 'xargs') return partReads(rest.replace(/^(?:\s+-\S+(?:\s+\d+)?)*/, ''), whole)
+    if (head === 'git') return GIT_READS.has(/^(?:\s+-[Cc]\s+\S+|\s+-\S+)*\s+(\S+)/.exec(rest)?.[1] ?? '')
+    if (head === 'do' || head === 'then' || head === 'else') return rest.trim() === '' || partReads(rest, whole)
+    return true
+}
+
+/** the call only read: a read tool, or a Bash command of a read shape (a for
+ *  loop over one included) whose every part reads */
+export function isReadOnly(c: { tool: string; shape: string; cmd: string }): boolean {
+    if (READ_TOOLS.has(c.tool)) return true
+    if (c.tool !== 'Bash' || !READ_SHAPES.has(c.shape.replace(/^\(for\) /, ''))) return false
+    return parts(c.cmd).every((p) => p.trim() === '' || partReads(p, c.cmd))
+}
+
+/** a call issued this soon after the one before, while that one still ran,
+ *  went out in the same turn */
+export const PARALLEL_MS = 2000
+
+/** one flag per call (sorted by start, closeCalls): it started before the
+ *  previous call ended, within PARALLEL_MS of its start */
+export function parallelFlags(calls: readonly Closed[]): boolean[] {
+    return calls.map((c, i) => {
+        const prev = calls[i - 1]
+        return prev != null && c.start < prev.stop && c.start - prev.start <= PARALLEL_MS
+    })
+}
+
+/** the turn metrics of a set of streams */
+export type TurnStats = { calls: number; reads: number; parallel: number; model: number }
+
+export const emptyTurns = (): TurnStats => ({ calls: 0, reads: 0, parallel: 0, model: 0 })
+
+export const addTurns = (into: TurnStats, t: TurnStats): TurnStats => {
+    into.calls += t.calls
+    into.reads += t.reads
+    into.parallel += t.parallel
+    into.model += t.model
+    return into
+}
+
+/** what a read shape costs in model turns: its calls, and the model time of
+ *  the turns that issued them */
+export type ReadCost = { shape: string; calls: number; model: number }
+
+/** a read call's name in the cost table: its tool, or its Bash shape */
+export const readName = (c: { tool: string; shape: string }): string => (c.tool === 'Bash' ? c.shape : c.tool)
+
+/** the turns of one stream: `model` is its model bucket, `turnModel` the
+ *  per call share wallBreakdown filled; read calls add to `costs` */
+export function turnsOf(calls: readonly Closed[], model: number, turnModel: Float64Array, costs: Map<string, ReadCost>): TurnStats {
+    const par = parallelFlags(calls)
+    const t: TurnStats = { calls: calls.length, reads: 0, parallel: 0, model }
+    calls.forEach((c, i) => {
+        if (par[i]) t.parallel++
+        if (!c.read) return
+        t.reads++
+        const name = readName(c)
+        const row = costs.get(name) ?? { shape: name, calls: 0, model: 0 }
+        row.calls++
+        row.model += turnModel[i] ?? 0
+        costs.set(name, row)
+    })
+    return t
+}

package/src/assets/kits/identity-kit.ts

@@ -15,6 +15,7 @@ import { mkdirSync } from 'fs'
 import { dirname, join } from 'path'
 import sharp from 'sharp'
 import { defineKind, type CanvasGen, type ComfyGen, type Kind } from '../kit-config.ts'
+import { HOUSE_FAMILIES, type TrailerLookInput } from '../../trailer/look.ts'
 
 export type Brand = {
     name: string
@@ -29,6 +30,9 @@ export type Brand = {
     /** og layout hook — replaces the WHOLE default card (bg + mark left +
      *  name/tagline right); the hook owns compositing the mark if it wants one */
     drawOg?: (ctx: SKRSContext2D, brand: Brand, size: { w: number; h: number }) => void
+    /** the look every trailer of the repo wears (titles, card, face, logo);
+     *  each value left out is derived from the palette (trailer/look.ts) */
+    trailer?: TrailerLookInput
 }
 
 export const FAVICON_SIZE = 512
@@ -52,9 +56,9 @@ export function identityKinds(brand: Brand): Kind[] {
 }
 
 // named faces first: the generic sans-serif can resolve to a face with no
-// Latin-1 accents (macOS). Each family below carries them, and an absent one
-// is skipped (macOS, Windows, then the common Linux faces)
-const OG_FAMILIES = 'Helvetica, Arial, "DejaVu Sans", "Liberation Sans", "Noto Sans", sans-serif'
+// Latin-1 accents (macOS). Each family carries them, and an absent one is
+// skipped (macOS, Windows, then the common Linux faces)
+const OG_FAMILIES = HOUSE_FAMILIES
 export const ogFont = (px: number, bold = false): string => `${bold ? 'bold ' : ''}${px}px ${OG_FAMILIES}`
 
 // shrink px until text fits maxW (og cards must never clip the tagline)

package/src/assets/run-assets.ts

@@ -122,14 +122,28 @@ async function repoWebRoot(root: string): Promise<string> {
 
 export type IdentityRender = { written: string[] } | { blocked: string }
 
-export async function renderIdentityNow(root: string): Promise<IdentityRender> {
+/** the repo's brand, `.shipkit/identity/brand.ts`: null when the file is
+ *  absent, a string saying why when it does not default-export one */
+export async function loadBrand(root: string): Promise<Brand | null | string> {
     const brandPath = join(root, '.shipkit/identity/brand.ts')
-    if (!existsSync(brandPath)) return { blocked: 'no .shipkit/identity/brand.ts — create one exporting a Brand (name, palette, mark)' }
+    if (!existsSync(brandPath)) return null
     // cache-bust: bun caches dynamic imports for the process lifetime — a
     // long-running hub must re-render the EDITED brand, not the cached one
     const mod = (await import(`${brandPath}?v=${await brandHash(root)}`)) as { default?: Brand }
-    if (mod.default == null) return { blocked: '.shipkit/identity/brand.ts must default-export the Brand' }
-    const brand = mod.default
+    return mod.default ?? '.shipkit/identity/brand.ts must default-export the Brand'
+}
+
+/** the rendered logo of the identity set, repo relative, when it exists */
+export async function identityLogo(root: string): Promise<string | null> {
+    const web = await repoWebRoot(root)
+    const file = web === '.' ? 'logo.png' : `${web}/logo.png`
+    return existsSync(join(root, file)) ? file : null
+}
+
+export async function renderIdentityNow(root: string): Promise<IdentityRender> {
+    const brand = await loadBrand(root)
+    if (brand == null) return { blocked: 'no .shipkit/identity/brand.ts — create one exporting a Brand (name, palette, mark)' }
+    if (typeof brand === 'string') return { blocked: brand }
     let markFile: string | undefined
     if (brand.mark.backend === 'comfy') {
         // comfy marks render from the PICKED identity-logo roll — the kit

package/src/checks/SK004-gitignore-policy.check.ts

@@ -32,6 +32,10 @@ const CONTRIB = '# repo-contributed lines (repo.config.ts gitignore:)'
 
 const DRAFTS_BACK = '!.comfy-ts/drafts/'
 
+/** re-includes a private repo carries and a declared public one drops: a
+ *  draft names private loras, a plan or a board quotes the owner */
+const PRIVATE_ONLY: ReadonlySet<string> = new Set([DRAFTS_BACK, `!${LAYOUT.plans}/`])
+
 export const POLICY_LINES = [
     // everything shipkit keeps lives under .shipkit/ (core/layout.ts). Local
     // by default: the private notes, drafts, venue listings and caches, and the
@@ -45,12 +49,13 @@ export const POLICY_LINES = [
     // asks git about it: a negation below the block that exposed the keyword
     // list would otherwise pass as a venue override
     `${LAYOUT.private}/`,
-    // the scratch and the review files, spelled out for the same reason: a
-    // review narrates agent process, and a plan names what nobody published
+    // the scratch and the review files, spelled out for the same reason:
+    // nothing durable lives in the scratch, and a review narrates agent process
     `${LAYOUT.tmp}/`,
     `${LAYOUT.reviews}/`,
     // a root scratch stays out of git too: the fix pass moves it under
-    // .shipkit/, and until it runs, a plan there is still private
+    // .shipkit/, its dated plans into .shipkit/plans/, and until it runs
+    // nothing there is exposed
     `${LEGACY_TMP}/`,
     'CLAUDE.local.md',
     // atomicWrite lands every file via `.<name>.tmp-<pid>` next to its target,
@@ -74,9 +79,9 @@ export const POLICY_LINES = [
 ]
 
 /** the policy one repo carries. A declared public tree ships to strangers,
- *  so the drafts stay ignored there: a draft holds the prompts and values
- *  behind generated assets, authored state in a private repo */
-const policyLines = (config: RepoConfig): string[] => declaredPublic(config) ? POLICY_LINES.filter((l) => l !== DRAFTS_BACK) : POLICY_LINES
+ *  so its drafts and plans stay ignored there: authored state in a private
+ *  repo, private words in a public one */
+const policyLines = (config: RepoConfig): string[] => declaredPublic(config) ? POLICY_LINES.filter((l) => !PRIVATE_ONLY.has(l)) : POLICY_LINES
 
 const LEGACY = '# the old root layout, ignored until the fix pass moves it under .shipkit/'
 

package/src/checks/SK013-one-way-in-policy.check.ts

@@ -14,7 +14,7 @@
 // scaffold, so a policy written there would bind exactly one checkout.
 import { isAbsolute, join } from 'path'
 import { inferBin } from '../core/canonical-scripts.ts'
-import { denyRules, GIT_STASH_RULE, RAW_RUNNERS } from '../core/one-way-in-policy.ts'
+import { denyRules, GIT_STASH_RULES, LEGACY_STASH_RULE, RAW_RUNNERS } from '../core/one-way-in-policy.ts'
 import { rootPublishesNpm } from '../core/repo-facts.ts'
 import type { RepoConfig } from '../repo-config.ts'
 import { repoOff } from '../core/when.ts'
@@ -139,9 +139,12 @@ export const oneWayInPolicy = check({
             return
         }
         const have = new Set(s.permissions?.deny ?? [])
-        const missing = want.filter((r) => !have.has(r) && r !== GIT_STASH_RULE)
-        if (!have.has(GIT_STASH_RULE))
-            c.fail(`${SETTINGS_PATH}: no "${GIT_STASH_RULE}" deny row, so an agent can stash every other agent's uncommitted work in a shared tree`)
+        const missing = want.filter((r) => !have.has(r) && !GIT_STASH_RULES.includes(r))
+        const stashMissing = GIT_STASH_RULES.filter((r) => !have.has(r))
+        if (stashMissing.length > 0)
+            c.fail(`${SETTINGS_PATH}: ${stashMissing.length} stash deny row(s) missing (${stashMissing.slice(0, 2).join(', ')}${stashMissing.length > 2 ? ', …' : ''}), so an agent can stash every other agent's uncommitted work in a shared tree`)
+        if (have.has(LEGACY_STASH_RULE))
+            c.fail(`${SETTINGS_PATH}: the blanket "${LEGACY_STASH_RULE}" row also refuses the read only \`git stash list\` and \`git stash show\``)
         if (missing.length > 0)
             c.fail(`${SETTINGS_PATH}: ${missing.length} raw runner(s) still permitted (${missing.slice(0, 3).join(', ')}${missing.length > 3 ? ', …' : ''}) — those calls never reach shipkit, so nothing is cached and no run can be attached to`)
         const guard = guardHookCommand(s)
@@ -172,7 +175,7 @@ export const oneWayInPolicy = check({
         // replacement is named while the guard cannot run is the green that
         // measured nothing, one line under the WARN that says otherwise
         if (!c.failed)
-            c.ok(`${SETTINGS_PATH} closes ${want.length - 1}/${RAW_RUNNERS.length} raw runner(s) and refuses git stash${guardRuns ? ', with the replacement named' : ' (the guard that names the replacement is declared, not yet runnable)'}`)
+            c.ok(`${SETTINGS_PATH} closes ${want.length - GIT_STASH_RULES.length}/${RAW_RUNNERS.length} raw runner(s) and refuses git stash${guardRuns ? ', with the replacement named' : ' (the guard that names the replacement is declared, not yet runnable)'}`)
     },
     // MERGES, never rewrites: this file also carries the attribution silencer,
     // a repo's own allow list and its own hooks, and clobbering those to fix a
@@ -185,11 +188,13 @@ export const oneWayInPolicy = check({
         if (existing == null && c.exists(SETTINGS_PATH)) return { changed: false, summary: `${SETTINGS_PATH} is unparseable — repair it by hand first, a merge would destroy it` }
         const s: Settings = existing ?? {}
         const changes: string[] = []
-        const deny = s.permissions?.deny ?? []
+        const old = s.permissions?.deny ?? []
+        const deny = old.filter((r) => r !== LEGACY_STASH_RULE)
+        if (deny.length < old.length) changes.push(`the blanket ${LEGACY_STASH_RULE} row replaced by one row per stash write`)
         const added = want.filter((r) => !deny.includes(r))
-        if (added.length > 0) {
+        if (added.length > 0 || deny.length < old.length) {
             s.permissions = { ...s.permissions, deny: [...deny, ...added] }
-            changes.push(`${added.length} deny rule(s) added`)
+            if (added.length > 0) changes.push(`${added.length} deny rule(s) added`)
         }
         const wantGuard = await guardCommandFor(d)
         if (!hasGuardHook(s)) {

package/src/cli/cmd_Calls.ts

@@ -0,0 +1,53 @@
+// `<cli> calls`: the call log (cli/kit/calls.ts) read back. shipkit logs every
+// run machine wide, because one sk serves every repo; a project CLI logs under
+// its own root. One command class for both: only the log file differs.
+import { Command, Option } from 'clipanion'
+import { homedir } from 'os'
+import { callsFile, callsReport, envPrefix, renderCallsReport, sinceOf } from './kit/calls.ts'
+
+export class CallsCommand extends Command {
+    static override paths = [['calls']]
+
+    static override usage = Command.Usage({
+        category: 'Health',
+        description: 'every sk run logged with its time: per command how often, how long, and the slowest runs',
+        details: 'reads ~/.shipkit/logs/sk-calls.jsonl, where every sk run writes a start line and an end line (time, cpu, memory, exit code). A run with no end line was killed or still runs. Runs another sk spawned are left out unless --nested. SK_LOG=off writes nothing; SK_AGENT names who ran it.',
+        examples: [
+            ['what agents waited on today', 'sk calls --since 1d'],
+            ['one command family', 'sk calls --cmd ci'],
+            ['only the runs started in this repo', 'sk calls --here'],
+            ['as json', 'sk calls --json'],
+        ],
+    })
+
+    since = Option.String('--since', { description: '30m, 2h, 3d or a date: only the runs that started after' })
+    cmd = Option.String('--cmd', { description: 'a command path prefix' })
+    top = Option.String('--top', '10', { description: 'how many slowest runs to list' })
+    nested = Option.Boolean('--nested', false, { description: 'keep the runs another run spawned' })
+    here = Option.Boolean('--here', false, { description: 'only the runs started inside the current folder' })
+    json = Option.Boolean('--json', false, { description: 'the report as json' })
+
+    /** the log this command reads */
+    logFile(): string {
+        return callsFile(homedir(), 'sk')
+    }
+
+    async execute(): Promise<number> {
+        const bin = this.cli.binaryName
+        const file = this.logFile()
+        const since = this.since == null ? undefined : sinceOf(this.since, Date.now())
+        if (since === null) { this.context.stderr.write(`FAIL: --since ${this.since}: 30m, 2h, 3d or a date\n`); return 2 }
+        const { existsSync, readFileSync } = await import('fs')
+        if (!existsSync(file)) { this.context.stdout.write(`no call yet: ${file}\n`); return 0 }
+        const r = callsReport(readFileSync(file, 'utf8'), {
+            since,
+            cmd: this.cmd,
+            top: Number(this.top),
+            nested: this.nested,
+            under: this.here ? process.cwd() : undefined,
+            self: process.env[`${envPrefix(bin)}_CALL`],
+        })
+        this.context.stdout.write(this.json ? `${JSON.stringify({ file, ...r })}\n` : renderCallsReport(bin, r, file))
+        return 0
+    }
+}