intOrEmpty stringifies n unless it's zero, in which case it returns "" — useful for TSV cells where 0 means "no data" rather than literal zero.

isAccessibilityDenied reports whether an osascript failure looks like a missing-Accessibility-permission error. Patterns are the standard error fragme

isNoBindingErr is a small predicate for the dispatch-session case. Callers use it to differentiate "no current binding" from real scan errors when rev

kbFiles returns the absolute paths of all existing KB files under the given flow root, in the canonical order (user, org, products, processes, busines

listUpdateFiles returns absolute paths to all *.md files under dir, sorted ascending. Missing dir yields an empty slice, not an error.

liveSessionsForTasks returns a merged id→count map across every unique harness referenced by the given task slice. Calls each harness's LiveSessionIDs

loadOwnerArg parses a single owner-slug argument, opens the DB, and loads the owner. On any error it reports to stderr, closes the DB, and returns a n

ownerTickManual implements `flow owner tick <slug>`: a hand-triggered, on-demand tick (wake the owner now, regardless of schedule). Interactive by def

ownerTickStale reports whether a recorded tick has been "running" longer than ownerTickStaleAfter (so its pid should not be trusted).

parseBackgroundAgents decodes `claude agents --json` into the harness's normalized BackgroundAgent slice. Only `kind:"background"` entries are returne

readSkillVersion returns the version string recorded in the harness's skill-version sidecar, or "" if missing/unreadable.

recordOwnerTick stamps last_tick_at + last_tick_status and clears the running-tick bookkeeping (the tick is over). Targeted update — it never touches

renderCardPNG draws the flow-branded share card and returns the image.

runSlugExists returns true iff a tasks row with the given slug exists. Checks all tasks (any kind) since slug is the primary key.

stubAutoRunner replaces autoRunner with fn.

stubNewUUID pins claude.NewUUID to a fixed value for the duration of the test.

visibleWidth returns the number of terminal cells s occupies, after stripping ANSI SGR escape sequences. Known wide runes count as 2 cells.

writeSkillVersion records `v` as the version of the binary that installed the current skill content. Errors are non-fatal — failing to write the sidec

ActivateOwner marks an owner active, schedules its next wake, and CLEARS archived_at — so `flow owner start` un-retires a retired owner (otherwise Due

ComputeSavings applies the counterfactual model. TotalHours sums only the two time-valued levers (automation + context-switch); ContextTokens (tokens)

GetTaskTagsBatch returns tags for many tasks in one query, keyed by task slug. Used by list output to avoid N+1 queries.

InstallUserPromptSubmitHook idempotently registers `command` as a UserPromptSubmit hook (no matcher). Fires on every user prompt; the command itself n

ListAllTags returns every distinct tag in use, with the number of non-archived tasks that carry it. Sorted by count descending, then tag ascending — m

Session allocation ----------------------------------------------- NewSessionID returns the session id flow should claim before spawning. Implementati

PauseOwner marks an owner paused (targeted; preserves every other column, including any in-flight tick bookkeeping).

Prune drops cache entries whose path was not seen in the latest run.

RenderJSON encodes v as indented JSON. Callers should pass a slice of concrete structs (or maps) — json.Marshal handles key ordering for structs based

RenderJSONL renders a claude session jsonl byte-stream to w. Exposed (not just used by RenderTranscript) so tests can exercise the decoder against fix

ResolveTaskProjectOrPlaybook resolves a ref that could be a task, project, or playbook. Supports task/, project/, playbook/ prefixes. On bare refs, tr

ResumeBackground brings a no-longer-tracked background session's conversation back as a fresh background agent, seeded from the prior session's transc

Save writes the cache as JSON.

ScanJSONL reads a Claude session jsonl byte-stream and extracts a FileRollup. ownSlug is the slug of the task that owns this transcript, used to disti

SetOwnerNextWake sets ONLY next_wake_at (targeted column write). Used by `flow owner next` and a tick's self-pacing. It deliberately does not load+rew

ShellQuote wraps s in single quotes with proper escaping. Same implementation as iterm.ShellQuote / terminal.ShellQuote / zellij.ShellQuote.

SkillVersionPath returns the sidecar file recording which flow binary version wrote the current skill content. Used by the auto-upgrade gate.

SkipPermissionsRun executes a non-interactive prompt against the harness with per-tool approvals auto-allowed (used by `flow done`'s close-out sweep).

Truncate shortens s to maxRunes runes, appending an ellipsis when the string was actually shortened. maxRunes <= 0 disables truncation.

UpdateOwner persists an owner's mutable fields (name, work_dir, project_slug, status, every, scheduling, last-tick bookkeeping, harness) by slug and r

ValidateSession verifies that the on-disk state for (workDir, sessionID) is consistent with what a future `flow do <slug>` resume would expect — for c

bgStateLabel renders a background agent's coarse condition for user messages, e.g. "busy/working" while live or just "stopped" once exited.

buildAutoBootstrapPrompt is the bootstrap prompt for a headless, unattended run. It differs from the interactive prompt in two load- bearing ways: (1)

buildBootstrapPrompt is a backwards-compat shim for old callers that pass only a slug. Now points at the regular-task variant. Tests still call this t

buildTabTitle returns a short iTerm tab title. Project-scoped tasks get "<project-slug>/<task-slug>"; floating tasks get just "<task-slug>". Titles lo

buildTaskBootstrapPrompt is the prompt for regular tasks.

bumpWorkdirUsed updates workdirs.last_used_at, best-effort.

countFiles counts files ending in ext inside <base>/*/<sub>/.

daysInStatus returns the number of days the task has been in its current status. Uses status_changed_at if set, else falls back to created_at.

daysUntilDue returns the number of days until the due date. Negative means overdue. Returns (0, false) if no due date is set.

emitHookContext marshals a hookSpecificOutput payload for the given Claude Code hook event name. Used by both SessionStart and UserPromptSubmit hook h

emitSessionStartContext is a thin wrapper around emitHookContext for the SessionStart event.

escapeAppleScriptString escapes a string for safe embedding in a double-quoted AppleScript string literal. Same implementation as the sibling packages

extractWorkdirStringFlag pulls a `--flag val` or `--flag=val` pair out of args, returning (value, remaining, error). Returns ("", args, nil) if absent

installHook idempotently adds a hook entry for `event` to ~/.claude/settings.json. matcher may be empty — some events don't use one and the field is o

kbSeeds returns the five canonical KB files. Kept as a function (not a package-level var) so tests can call it directly without sharing state. The ski

launchAndCapture runs a `claude --bg …` command in workDir, parses the short id from its banner, and resolves the full session id by matching that sho

loadInjectionText resolves --with / --with-file into the text that will be injected as the session's first user message. For --with-file we don't embe

lookupBoundTask returns the task whose session_id matches $CLAUDE_CODE_SESSION_ID, or nil if no such task exists, the env var is unset, or the DB look

newUUID generates a v4 UUID in the 8-4-4-4-12 hex format that `claude --session-id` accepts.

ownerDirFor returns the absolute on-disk directory for an owner ($FLOW_ROOT/owners/<slug>) — where its charter and journal live. Tick prompts use this

ownerList implements `flow owner list` — one row per owner with its status, interval, and next scheduled tick.

ownerNextTickLabel renders the "next tick" column: the scheduled next_wake_at with a relative hint, or a parenthetical status when the owner isn't act

ownerShow renders the owner's accountability surface: metadata, next tick, and a live list of what it owns (tasks tagged owner:<slug>), split into in-

parseBackgroundBanner extracts the short id from `claude --bg`'s banner (`backgrounded · <shortId> · <name>`). Reads only the first line — the help li

parseSince converts "today" / "monday" / "7d" / "YYYY-MM-DD" / "Nd" into an absolute time lower bound, interpreted in local time. `now` is passed in f

quoteAppleScriptString returns an AppleScript expression that evaluates to s. Lines are emitted as separate quoted strings joined with `& linefeed &`,

---------- resolution helpers ---------- resolveTaskRef resolves a ref to a task. Includes archived rows so `show task` can display them.

scanForGitRepos walks root up to maxDepth levels, recording parent directories of any `.git` subdirectory it finds. maxDepth of 3 means root/a/b/c/.gi

setArchivedAt is the shared mutation: archive=true sets archived_at to now, archive=false clears it.

---------- hooks ---------- settingsPath returns ~/.claude/settings.json.

statsWithAutomation returns a Stats value with non-zero automation counters.

Color palette. Red is reserved for anomaly signals (overdue / stale). "high" priority is the dominant active state for daily users, so coloring it red

stubClaudeStatMissing makes claude.ValidateSession refuse every pair as "file not found." Models the chained-cd cheat and any other case where the on-

taskStaleness returns (daysSinceLastTouch, stale) for an in-progress task. "Last touch" is max(updated_at, newest update file mtime). Staleness thresh

uninstallHook removes any entry under hooks.<event> whose inner hook list contains a command matching `command`. Returns (removed=true) iff the file c

weekStart returns Monday 00:00 UTC of t's ISO week (zero in → zero out).

writeCard renders the HTML card to a file.

writeCardPNG renders the PNG card and writes it to path.

BackgroundAgents runs `claude agents --json --all` and decodes the registry. --all includes exited / failed / completed sessions (not just live ones)

ClearTaskTags removes all tags from a task.

RemoveTaskTag detaches a tag from a task. No error if the pair doesn't exist; caller can pre-check via GetTaskTags.

Transcripts ------------------------------------------------------ RenderTranscript reads the harness's on-disk transcript for (cwd, sessionID) and wr