ShellJobRegistry class final

The session's background shell jobs. See the library doc.

Constructors

ShellJobRegistry({required ExecutionEnv env, void onStart(ShellJobEntry job)?, void onSettled(ShellJobEntry job)?, void onStaleJobLog(String message)?, int? jobLogMaxBytes, void onJobLogWarning(String message)?, String? jobLogDir, String jobLogRedactor(String text)?, int maxRetainedExitedJobs = defaultMaxRetainedExitedJobs, DateTime? bootTime})

Creates a registry over env; onStart fires when a job starts (the hub's start block), onSettled when a job exits. jobLogMaxBytes and onJobLogWarning (issue #919) are merged into every start's options — the size ceiling and the low-disk warning channel; null bytes means the shells' built-in default. A caller's own options values take precedence over these session defaults.

Properties

env → ExecutionEnv

The environment jobs run in.

final

hashCode → int

The hash code for this object.

no setter, inherited

isSupported → bool

Whether the environment can run detached jobs at all.

no setter

jobLogDir → String?

Where job logs live (issue #1408 AC1); defaults to <cwd>/.fah/bash_jobs. Bench/unattended runs point this OUTSIDE the task workspace (env FAH_JOB_LOG_DIR, e.g. the container's /tmp) so the graded diff never sees harness artifacts.

final

jobLogMaxBytes → int?

Log size ceiling merged into every job start (issue #919); null lets the shell apply its built-in default (defaultJobLogMaxBytes).

final

jobLogRedactor → String Function(String text)?

At-rest redaction merged into every job start (issue #1408 AC2) — typically RedactionPipeline.redact. Secret-shaped output becomes [REDACTED:<kind>] markers in the log FILE; null keeps raw bytes (hosts that run no pipeline). A caller's per-call ShellExecOptions.jobLogRedactor wins over this session default.

final

jobs → List<ShellJobEntry>

All jobs of this session, oldest first.

no setter

maxRetainedExitedJobs → int

The exited-entry retention cap; see defaultMaxRetainedExitedJobs.

final

onJobLogWarning → void Function(String message)?

Low-disk warning channel merged into every job start (issue #919) — fired at most once per job, when log writes stop.

final

onSettled → void Function(ShellJobEntry job)?

Fires on every job exit — the host's terminal bookkeeping (job board, waiting row) hangs off it. Whether the MODEL is also told is the host's call, via ShellJobEntry.notifyOnSettle (issue #562).

final

onStaleJobLog → void Function(String message)?

Fires at most ONCE per session when a background-job log with the old, pre-unique-id name (sh-<n>.log) is modified after this registry was created — proof that another fa process on an older build shares this directory and its job output can interleave with stale files. Hosts surface it as a "restart that instance" hint.

final

onStart → void Function(ShellJobEntry job)?

Fires when a job successfully starts (issue #277 task blocks).

final

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

Methods

job(String id) → ShellJobEntry?

Looks up a job by id, or null.

lookup(String id) → ShellJobLookup

Classifies id against the registry (gh-1438): an exact hit, a unique sh-<n>- near-miss resolved to its retained job (read-only — destructive actions never consume this), an ambiguous shared-n match, or unknown with the closest retained ids. Resolution never reads the disk — the post-GC log fallback is the caller's step.

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

prunedLogPath(String id) → String?

The on-disk log of a GC'd (pruned) exited job, or null when id was never pruned. The log may itself be gone (deleted by retention sweeps) — callers treat a failed read as today's clean unknown-id error (E2).

start(String command, {ShellExecOptions? options}) → Future<ShellJobEntry>

Starts command as a background job. Throws StateError with a clean note when the environment has no BackgroundShell capability.

tail(String id, {int maxLines = 50}) → Future<String>

Reads the last maxLines lines of the job's log (the whole log when shorter). Returns an empty string when nothing has been written yet.

tailFromLog(String path, {int maxLines = 50}) → Future<String?>

Reads the last maxLines lines of any job log path on disk — the post-GC exact-id fallback (gh-1438 AC4). Returns null when the file cannot be read (gone, deleted by retention sweeps).

toString() → String

A string representation of this object.

inherited

Operators

operator ==(Object other) → bool

The equality operator.

inherited

Constants

defaultMaxRetainedExitedJobs → const int

How many exited jobs the registry retains (gh-1438 second tier). Production monitor sessions ran thousands of short-lived jobs and the grow-only list kept every entry — with its log text — for the process lifetime. Beyond the cap the oldest-settled entries are pruned (LRU by settle time); their log FILES stay on disk and exact-id lookups fall back to them (prunedLogPath/tailFromLog, AC4). Running jobs are never pruned.