setupFlowRoot sets up a tempdir FLOW_ROOT and runs cmdInit to create the DB + tree. Returns the root path. Uses the init-test helper `initTempFlowRoot

---------- lifecycle ---------- NowISO returns the current time formatted as RFC3339.

captureStdout redirects os.Stdout and os.Stderr during f and returns combined output.

seedTask creates a minimal task row (floating, workspace work_dir).

cmdAdd dispatches `flow add project|task|playbook ...`.

showListEditDB is the test harness used by cmd_show, cmd_list, and cmd_edit tests. It sets FLOW_ROOT, creates projects/ and tasks/ subtrees, opens flo

cmdList dispatches `flow list tasks|projects|playbooks|runs|tags|owners`.

cmdDo flips a task to in-progress, bootstraps a Claude session if needed (race-free via atomic UPDATE ... WHERE session_id IS ?), and spawns an iTerm

OpenDB opens (or creates) the SQLite database at path, ensures the schema is present, and runs idempotent migrations. The connection is opened with b

CreateOwner inserts a new owner. Status defaults to 'active' and timestamps are stamped if unset. NextWakeAt is left as-is (NULL until the owner is st

stubITerm replaces iterm.Runner with a counter + captured-script recorder. Returns the counter pointer and a function that reads the most recent Apple

cmdUpdate dispatches `flow update task|project`. The command is the canonical lane for in-place field edits — including legacy field setters (priority

flagSet creates a named flag.FlagSet that prints errors instead of exiting.

cmdOwner dispatches `flow owner list|show|start|pause`.

cmdShow dispatches `flow show task|project|playbook|owner`. Per spec §5.4.

flowDBPath returns the absolute path to flow.db under the flow root. Returns a clear error if the data directory hasn't been initialized.

Identity --------------------------------------------------------- Name returns the canonical short id (stored on tasks.harness).

flowRoot returns the root directory for flow state. Honors $FLOW_ROOT if set, otherwise falls back to ~/.flow. The returned path is not guaranteed to

New returns a fresh claude harness. The struct is stateless; we expose it through the harness.Harness interface.

Wrap returns text decorated with the given ANSI code. When color is disabled or code is empty, the input is returned unchanged.

cmdSkill dispatches `flow skill install|uninstall|update`.

UpsertPlaybook inserts a new playbook or updates an existing row by slug. Updates touch name, project_slug, work_dir, updated_at; archived_at is not t

cmdRun handles `flow run <subcommand>`. Currently only `run playbook <slug>` is supported.

setupArchiveTestEnv creates a tempdir, sets FLOW_ROOT, initializes flow.db, and returns the opened handle. The db handle is closed on cleanup. We inte

withTempHome redirects $HOME to a tempdir for the duration of the test.

cmdInit creates ~/.flow/ (or $FLOW_ROOT), initializes flow.db, installs the skill. Idempotent — re-running is safe.

cmdWorkdir dispatches `flow workdir list|add|remove|scan`.

cmdDone marks a task done. Per spec §5.3 this is a single UPDATE that does NOT touch the iTerm tab, kill the Claude session, or clear session_id — the

fakeSessionID makes a deterministic v4-shaped UUID derived from slug. Used by insertTask to satisfy the session-id invariant on non-backlog rows witho

SpawnTab opens a new Warp tab in cwd via the warp:// URI, then injects `command` (with envVars set, title set, and cwd entered) by keystroking the pat

cmdArchive sets archived_at = now() on the matching row.

FocusSession tries to focus the kitty window currently running `binary` with the given session UUID. The `binary` arg is the harness's executable name

SessionIDEnvVar returns the env var the harness exports inside each running session so flow can reverse-lookup the bound task (e.g. "CLAUDE_CODE_SESSI

cmdEdit opens a brief.md in $EDITOR for either a task or a project. Per spec §5.5. Bumps updated_at after a clean editor exit.

hexColor parses "#RRGGBB" into an opaque color.

---------- transcript ---------- RenderTranscript and the jsonl decoder it uses live in transcript.go in this package. EncodeCwd encodes an absolute

FocusSession tries to focus the zellij pane currently running `binary` with the given session UUID. The `binary` arg is the harness's executable name

FocusSession tries to focus the iTerm2 session whose underlying process is `binary` running with `--session-id <sessionID>` or `--resume <sessionID>`

AddTaskTag attaches a tag to a task. Idempotent: re-adding an existing (task_slug, tag) pair is a no-op via INSERT OR IGNORE.

DefaultConstants are the shipped defaults.

Detect returns the backend that SpawnTab will use for the current process environment. Exposed so callers (and tests) can inspect the choice without s

allHarnesses returns every implemented harness adapter. The slice is the registry that ambient-harness detection and harnessByName consult. Adding cod

bgAgentsJSON builds a `claude agents --json` array of LIVE entries (pid set) — one per session id (short id = first 8 chars).

ResolvePlaybook resolves a ref to exactly one playbook by slug. includeArchived controls whether archived rows are eligible.

Slugify converts a free-form name into a URL-safe slug. It lowercases, replaces runs of non-alphanumeric chars with dashes, strips leading/trailing da

SpawnTab opens a tab in the auto-detected backend. The contract matches every backend's SpawnTab.

Total is all tokens flow-managed sessions actually processed.

---- tiny helpers ----

initTempFlowRoot points FLOW_ROOT at a tempdir AND redirects $HOME so skill install lands inside the tempdir as well. Isolates every init test from th

withFakeHTTP swaps httpGetForVersion for the duration of the test.

ColorEnabled reports whether ANSI color codes should be emitted to w. Color is disabled when forceOff is true, when the NO_COLOR env var is set (per h

DueOwners returns active, non-archived owners whose next_wake_at is set and at or before nowISO — i.e. the owners the scheduler should tick now. Pause

FocusSession tries to focus the Terminal.app tab whose underlying process is `binary` running with `--session-id <sessionID>` or `--resume <sessionID>

GetTaskTags returns the tags on a single task, sorted alphabetically.

LoadCache reads a cache file. A missing or corrupt file yields an empty (usable) cache — never an error. Stats must never fail on a bad cache.

Render writes the table to w. Trailing whitespace is trimmed from every emitted line so an empty last cell doesn't litter output with spaces.

RenderTSV emits a tab-separated values stream with a header row.

---------- exact-match resolvers ---------- All ref resolution is exact match on slug (case-insensitive). ResolveTask resolves a ref to exactly one t

cmdDoHere is the `--here` branch of `flow do`. Instead of spawning a new tab with a fresh Claude session, it binds the CURRENT Claude session (discove

cmdOwnerTick is the hidden `flow __owner-tick <slug>` supervisor that runs inside the detached process: build the tick prompt, run the owner's harness

defaultHarness returns the adapter for code paths that have no task context (e.g. `flow init`, `flow skill install`, the SessionStart hook handler bef

harnessForTask returns the adapter for the task's stored harness. NULL/empty harness column → claude+nil (back-compat). Unknown non-empty name → nil+e

humanCompact formats large numbers with B/M/K suffix for compact display. ≥1B → "X.XXB"; ≥1M → "X.XXM"; ≥1K → "XK" or "X.XK"; else plain integer.

seedTaskAtCwd creates a task with work_dir set to the test process's current cwd. Used by --here tests that want to satisfy the cwd-mismatch invariant

stubBG installs a BGCommandRunner that dispatches on args[0]: spawn / resume calls get the banner (and are recorded), `agents` calls get the JSON. Ret

stubBGCommand swaps claude.BGCommandRunner with a recorder that dispatches on args: `agents` returns *agentsJSON (mutable so a test can change registr

stubBGMode forces spawner.IsBackground() true for the test.

stubClaudeStatOK makes claude.ValidateSession succeed for every (workDir, sessionID) pair, for tests that don't materialize fake jsonl files under a t

withFlowRoot points $FLOW_ROOT at a tempdir so version-cache writes don't touch the developer's real ~/.flow.

IsBackground reports whether flow should spawn this session as a terminal-free background agent ($FLOW_TERM=bg) rather than opening a terminal tab. bg

LatestRelease returns the latest tagged version of flow on GitHub as a tag string (e.g. "v0.1.0-alpha.3"), or "" if the lookup cannot be completed (of

ListOwners returns owners matching filter, sorted by slug. Archived owners are excluded unless IncludeArchived is set.

Live-session detection ------------------------------------------- LiveSessionIDs returns the count of running processes per session id. Used both for

---------- task tag queries ---------- NormalizeTag canonicalizes a tag for storage and comparison: trim whitespace, lowercase. Returns "" for input t

ParseFormat converts a user-supplied string into a Format. Empty string and "table" both yield FormatTable; "json" and "tsv" are the other accepted va

ResolveProject resolves a ref to exactly one project by slug.