SpawnBackground starts a fresh background session in workDir, running prompt, displayed as name. workDir is where the agent begins (and what its trans

SpawnTab opens a new kitty tab in the current OS window, sets its title and cwd, and types `command` into the new window's PTY. envVars are attached

ambientHarness probes the current process env for each known harness's session-id env var. Returns the matching adapter if exactly one is set; returns

boolStr renders booleans as "true"/"" so empty TSV cells stay visually quiet and don't clutter the grep'able stream.

buildOwnerTickPrompt is the bootstrap prompt for one headless owner tick. The owner reads its charter, reviews what it owns, acts, and parks any human

enumerateAuxFiles returns absolute paths to top-level *.md files in dir, excluding brief.md. Subdirectories (notably updates/) are not descended. Retu

generateRunSlug computes the unique slug for a new playbook run. Cascade: 1. <pb>--YYYY-MM-DD-HH-MM (default; minute precision) 2. <pb>-

humanInt formats n with thousands separators (e.g. 1041234 → "1,041,234"). Pure Go, no third-party deps.

openConcurrentDB opens flow.db with a generous busy_timeout so that two concurrent `flow do` processes (or two goroutines in the tests) will serialize

runJSON is a thin wrapper that reports errors as exit code 1.

stubAllRunners replaces every backend's Runner (plus warp's OpenURL/WriteScript and kitty's RunnerOutput) with no-op stubs that flip a per-backend boo

withVersion temporarily overrides the package-level Version for the duration of a test.

AutoRunArgv builds the argv for a headless, self-completing autonomous run (`flow do --auto`) pinned to sessionID. This is a third execution shape dis

BackgroundAgents returns the current background-agent registry (claude: `claude agents --json --all`, so exited / failed / completed sessions are incl

FocusSession tries to focus an existing tab/pane that is already running the named harness binary with the given session UUID. The `binary` arg is the

Launching -------------------------------------------------------- LaunchCmd builds the shell command to start a fresh session with the given session

ParseSince converts a --since value to a lower-bound time. "all"/"" → zero (no bound); "<N>d" → now minus N days; otherwise RFC3339.

ShellQuote wraps s in single quotes with proper escaping.

ShellQuote wraps s in single quotes with proper escaping. Identical to iterm.ShellQuote / terminal.ShellQuote / zellij.ShellQuote.

SpawnTab opens a new Terminal.app tab with the given title, cwd, and command. envVars are attached as an inline prefix to `command` only — so they are

SpawnTab opens a new zellij tab in the current session, sets its name and cwd, and types `command` into the new pane's PTY. envVars are attached as a

addListFlags registers the common --format / --no-color / --no-truncate flags on fs. Slugs are never truncated — only the freeform waiting field has a

appendStaleVersionHint returns a short suffix to add to SessionStart hint payloads when the local flow binary is older than the latest GitHub release.

bgAgentStatus returns the live background-agent entry for a task's bound session, or nil if the task isn't bg-bound, has no session, the harness can't

captureStderr redirects os.Stderr through an os.Pipe for the duration of the test and returns a closure that drains and returns whatever was written.

cmdTranscript implements `flow transcript <task-slug>`. It delegates to the task's harness for both path resolution and on-disk format decoding — each

currentSessionID returns this process's harness session id, or "" if not running inside any known harness. Probes every implemented harness's session-

dimHeaders wraps each header label in dim ANSI when color is enabled so the header line reads as supporting text rather than a row of data.

emptyResult prints the conventional "(no X)" line and returns 0. Honors the requested format: JSON emits "[]", TSV emits a header-only stream, table e

fakeHTTPResponse builds a *http.Response with the given JSON body.

maybeAutoUpgradeSkill checks the recorded skill version against the running binary's version and, if they differ, refreshes the skill + SessionStart h

reconcileAutoRun promotes a stale 'running' row to 'dead' when its supervisor pid is no longer alive (crash, kill -9, reboot — anything that prevented

resolveWorkDir canonicalizes path to an absolute path, verifies it exists (or mkdirs it if create=true). Returns the abs path.

seedRunningAuto creates an in-progress task already in auto 'running' state, as if a supervisor had just launched it.

stubAutoLauncher replaces autoLauncher with a recorder that returns a fixed pid and never spawns a real supervisor. Returns accessors for the captured

stubPS replaces claude.PSRunner with a canned-output stub so the live-session guard in cmdDo can be exercised without touching the real process table.

writeFakeEditor writes an executable script into dir that appends the text "edited by test" to any file path passed as its first argument. Returns the

writeFakeGitConfig creates a .git/config under dir with the given origin URL. Returns the absolute dir path.

BuildStats derives a Stats from flow.db + transcripts + on-disk dirs.

LoadConstants reads ~/.flow/stats.json. A missing file yields defaults silently; a corrupt file yields defaults with a stderr notice. Any field ≤ 0 (i

ResumeCmd builds the shell command to continue an existing session by id. opts.Inject (if any) is appended as the first turn after resume.

RetireOwner permanently stops an owner: sets status='retired' and archives it. It no longer ticks (DueOwners requires active) and is hidden from the d

ScanFile returns the rollup for a jsonl file, reusing the cached result when the file's mod time and size are unchanged.

ShellQuote wraps s in single quotes with proper escaping.

ShellQuote wraps s in single quotes with proper escaping.

Skill / rules file ----------------------------------------------- SkillInstallPath returns where flow's skill markdown lives for this harness (e.g. ~

TaskBySessionID returns the task bound to the given Claude session UUID, or sql.ErrNoRows if none. The partial unique index on tasks(session_id) WHERE

ValidateSessionID rejects strings that can't be a session id for this harness. Used by `flow do --here` to gate the env-var- supplied id before writin

buildOwnerTickPromptInteractive is the prompt for a hand-triggered tick run WITH the user present (often the first tick). Same orchestrate + journal d

buildPlaybookRunBootstrapPrompt is the prompt for playbook-run tasks. Adds an explicit `flow show playbook <slug>` context-load step and frames the ru

cmdAutoExec is the hidden `flow __auto-exec <slug>` supervisor. It runs inside the detached process the launcher started: build the autonomous prompt,

cmdStats implements `flow stats` — usage & ROI analytics derived from flow.db, session transcripts, and on-disk auto-runs/owner/kb dirs.

cmdUnarchive clears archived_at.

contains is a tiny strings.Contains shim so done_test.go doesn't need a strings import just for this.

detectGitRemote reads <path>/.git/config (if present) and extracts the origin remote URL. Returns "" on any error or if the section isn't present. Han

harnessByName looks up an adapter by stored Name. - Empty/NULL name → returns (claude, nil). Back-compat for pre-harness-column DB rows where the col

openFlowDBForWorkdir opens the flow DB and returns (db, rc). On error, it prints and returns a non-nil error rc.

parseDueDate converts a human-friendly date expression to a time.Time. Accepts: YYYY-MM-DD, today, tomorrow, weekday names (next occurrence), Nd (N da

renderCardHTML writes a self-contained HTML card for the stats.

renderReport prints the terminal analytics report.

renderToString is a tiny test helper around RenderJSONL.

resolveTranscriptPath locates a session's jsonl under ~/.claude/projects. It first tries the deterministic cwd-encoded path (~/.claude/projects/<Encod

sparkline renders ints as a unicode bar string (one rune per value).

stubAllFocusBackends replaces the per-backend PSRunner / RunnerOutput vars with stubs that flip a bool when the backend's FocusSession path runs. Rest

uniqueSlug returns base if no row with that slug exists in table; otherwise appends -2, -3, ... until it finds an unused one.

Binary returns the executable name (e.g. "claude", "codex"). Exposed so flow's process-table scan can filter to lines that mention the right binary.

DeleteOwner removes the owner row entirely. The caller is responsible for removing the on-disk owners/<slug>/ directory. Errors if no such owner. Owne

Hooks ------------------------------------------------------------ InstallSessionStartHook idempotently registers `command` as a SessionStart hook (ma

InstallSkill writes content to SkillInstallPath, creating parent dirs as needed. Idempotent — callers gate "already installed" themselves.

NullIfEmpty returns a *string pointing to s, or nil if s is empty.

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

ShellQuote is re-exported so callers don't need to import the chosen backend just to quote a value before handing it to SpawnTab. All backends quote i

---------- skill install ---------- SkillInstallPath returns ~/.claude/skills/flow/SKILL.md.

SpawnTab opens a new Ghostty tab with the given title, cwd, and command. envVars are attached as an inline prefix to `command` only — so they are pres

affectedOwnerRow checks an UPDATE result for the "exactly one owner matched" contract shared by the targeted owner-mutation helpers below.

autoChildEnv builds the environment for the detached supervisor. It inherits the parent's environment (so PATH finds claude and FLOW_ROOT points at th

backgroundLauncherFor returns the harness's BackgroundLauncher capability, or a clean error if the harness can't host background sessions. This is the

buildBootstrapPromptForKind dispatches to the right prompt variant based on task kind. For kind='playbook_run' the playbook variant is used; otherwise

buildBootstrapPromptForKindV2 is the kind-aware dispatcher with first- run awareness for playbook runs. When isFirstRun=true on a playbook run, a rich

cmdHookSessionStart emits a Claude Code SessionStart hook response. Wired via ~/.claude/settings.json with a matcher of "startup|resume" so it fires f

cmdHookUserPromptSubmit implements `flow hook user-prompt-submit`, wired as a Claude Code UserPromptSubmit hook that fires on every user prompt but do

currentSessionTask returns the task bound to this Claude session via tasks.session_id. Returns sql.ErrNoRows if the current session is unbound (dispat

finalizeAutoRun records a terminal auto-run status ('completed' or 'dead') and clears the supervisor pid. Best-effort: errors are returned for the cal

findTask resolves a user-supplied ref to exactly one non-archived task. Exact alias match first, then exact slug match.

harnessForSpawn returns the harness to use when bootstrapping a new session for a task: 1. If the task already has a harness set, look it up by name