@techierathore/techieflow 1.0.4 → 1.1.1

package/.tfcore/utils/tf-mockup-parity.sh

@@ -5,6 +5,28 @@
 #        --screen login=/login --screen harness=/harness --screen export=/export \
 #        --cookie 'AuthCookie=<value from your Playwright login>' \
 #        --json-out tests/.artifacts/mockup-parity/run.json
+#   A sign-in the page keeps for itself sets no cookie (AppManager TF-011): give it
+#        --login-path /login --user <u> --password <p>   (or --storage-state <file>)
+#   and each screen is opened in a tab that signed in through the form, the way
+#   tf-verify-screens.sh does; `widths[].reached` in the JSON says how a 401 screen was reached.
+#   --list tests/.artifacts/verify/list.json takes each screen's mockup path from the list
+#   tf-verify-list.sh wrote, so a mockup in a subfolder is found (Lekhak TF-022); with no --screen
+#   it drives every listed screen. Without a list, a mockup in a subfolder is used when it is the only one.
+#   A desktop head (Lekhak TF-006): --cdp http://<host>:9223 in place of --base attaches to the
+#   running app, as tf-verify-screens.sh --cdp does, and opens each route by pushState.
+#   The app is compared in the mockup's theme: the mockup's data-*theme/mode/scheme attributes on
+#   <html> and <body>, and a light/dark mode class there (class="dark", Lekhak TF-013), are set on the
+#   app page for the comparison and put back after (Lekhak TF-010);
+#   Then the screen is compared again in the other theme (Lekhak TF-024), the mockup drawn in it too:
+#   --themes light,dark runs both, light or dark alone only that one, and auto (the default) runs the
+#   other once the app shows it has it. Colour is not compared in a theme the mockup does not draw.
+#   Each finding of that pass carries "theme"; the result lists "themes" it was compared in.
+#   --keep-app-theme compares the theme the app shows, and only that one. A mockup box marked data-tf-state or
+#   data-state-testid (another state of the screen) is left out of the comparison (Lekhak TF-011),
+#   and so are its icons, badges and text when a box around it is compared (Chatur TF-001).
+#   A box marked data-tf-sample, or data-tf-state="sample-data" (Chatur TF-005), is sample data: compared
+#   when the app draws something in its place,
+#   otherwise listed in coverage.not_measured and taken off the boxes around it (Chatur TF-002).
 #
 # WHAT IT ASKS: "does the built screen carry the structure its approved mockup
 # draws?" — at the same viewports, comparing STRUCTURE, never pixels. Pixel diffing
@@ -47,7 +69,7 @@ set -uo pipefail
 
 HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
-case "${1:-}" in -h|--help) sed -n '2,42p' "$0"; exit 0 ;; esac
+case "${1:-}" in -h|--help) sed -n '2,56p' "$0"; exit 0 ;; esac
 
 command -v node >/dev/null 2>&1 || {
   echo "tf-mockup-parity: node is required (verify-phase §1 installs the verify environment)." >&2
@@ -62,4 +84,5 @@ node -e "import('playwright').then(()=>process.exit(0)).catch(()=>process.exit(1
   exit 4
 }
 
-exec node "$HERE/tf-mockup-parity.mjs" "$@"
+source "$HERE/tf-lock.sh"; tf_take_lock mockup-parity   # one browser check at a time (TF-048)
+node "$HERE/tf-mockup-parity.mjs" "$@"

package/.tfcore/utils/tf-owner-text.py

@@ -0,0 +1,233 @@
+#!/usr/bin/env python3
+"""tf-owner-text.py — check text written for the owner (MISS-TechieFlow-20260911-03).
+
+    bash .tfcore/utils/tf-owner-text.sh [--root <dir>] [--final] <file> ...
+    bash .tfcore/utils/tf-owner-text.sh [--root <dir>] [--final] --stdin      # the closing message
+
+Four checks, one per mistake that reached the owner in TfLens's hand-off of 2026-09-11
+(MISS-TfLens-20260911-01 to -03, and a fourth: two problems fixed upstream reported as open):
+
+  words     a word from .tfcore/standards/owner-words.txt, or a script's internal name such as
+            duration_s or PHASES_TOP_KEYS, in a sentence the owner reads
+  upstream  an upstream problem (an entry id in docs/*-Feedback.md: TF-022, TR-010 …) that is
+            still open sits in a table saying what it affects and whether it blocks or breaks
+            anything, and appears in a code block, which is the prompt that gets it fixed; one the
+            feedback file records as fixed upstream or closed is described as fixed or closed
+  commands  a framework command named in a sentence (*verify) appears in a code block holding
+            the line to paste
+  final     with --final, the text is a command's closing message and carries a code block: the
+            next prompt
+
+Text inside ``` blocks is what the owner pastes, so the words check skips it. A document that has
+its own template (BRD, checklist, feedback file …) is skipped: tf-doc-check.sh owns its shape.
+Exit 0 clean, 1 a FAIL, 2 could not run. Python 3 standard library only.
+"""
+from __future__ import annotations
+
+import glob
+import os
+import re
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+ANY_ID = re.compile(r"(?<![\w-])([A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*-\d+)\b")
+SCRIPT_NAME = re.compile(r"(?<![\w/.\-])([A-Za-z][A-Za-z0-9]*(?:_[A-Za-z0-9]+)+)(?![\w/\-]|\.\w)")
+COMMAND = re.compile(r"(?<![\w*])\*([a-z][a-z0-9]*(?:-[a-z0-9]+)*)\b")
+# a sentence that puts a command in front of the owner as work still to do
+TO_RUN = re.compile(r"(?i)\b(run|rerun|re-run|pending|next|not (?:yet )?(?:been )?run|still|should|must|"
+                    r"needs?|to do|waiting|before|then)\b")
+COMMANDS = {"verify", "build-phase", "fix-issues", "triage-issues", "triage-and-fix", "amend-docs",
+            "refresh-status", "handoff-phase", "log-miss", "deploy-checklist", "day1-greenfield",
+            "day1-brownfield", "devguide", "productguide", "metrics", "split-brd", "mockups", "yolo"}
+TEMPLATED = re.compile(
+    r"(?i)(?:-P\d+)?-(BRD|Architecture|UIDesign|Checklist|Deployment-Checklist(?:-[\w]+)?|Coding-Standards|"
+    r"UsageGuide|Usage-Guide|DevGuide|ProductGuide|Phases|Brief|Decision-Request|[\w.]+-Feedback|Misses)\.md$"
+    r"|(?:^|/)PROJECT-STATUS\.md$")
+
+
+def load_words(root):
+    for base in (os.path.join(root, ".tfcore", "standards"), os.path.join(HERE, "..", "standards")):
+        p = os.path.join(base, "owner-words.txt")
+        if os.path.isfile(p):
+            out = {}
+            for line in open(p, encoding="utf-8"):
+                if line.strip() and not line.lstrip().startswith("#") and "|" in line:
+                    w, say = (x.strip() for x in line.split("|", 1))
+                    out[w.lower()] = say
+            return out
+    return {}
+
+
+def upstream_state(root):
+    """Every entry id in the project's feedback files -> (state, where), from the one reader
+    every script uses (tf_feedback.py), so this check and PROJECT-STATUS can never disagree."""
+    sys.path.insert(0, HERE)
+    import tf_feedback
+    return tf_feedback.state_map(root)
+
+
+def split_text(text):
+    """-> (prose lines [(n, line)], the text inside code blocks)."""
+    prose, fenced, fence = [], [], None
+    for n, line in enumerate(text.splitlines(), 1):
+        m = re.match(r"^\s*(```|~~~)", line)
+        if m:
+            fence = None if fence == m.group(1) else (fence or m.group(1))
+            continue
+        (fenced if fence else prose).append((n, line) if not fence else line)
+    return prose, "\n".join(fenced)
+
+
+def units(prose):
+    """Group prose lines into the unit a sentence is read in: a table row (with its table's
+    header) or a paragraph. -> [(first line no, text, header or None)]"""
+    out, para, header, in_table = [], [], None, False
+
+    def flush():
+        if para:
+            out.append((para[0][0], "\n".join(t for _n, t in para), None))
+            para.clear()
+
+    for n, line in prose:
+        if line.lstrip().startswith("|"):
+            flush()
+            if not in_table:
+                header, in_table = line, True
+            elif not re.match(r"^\s*\|?\s*:?-{2,}", line):
+                out.append((n, line, header))
+            continue
+        in_table = False
+        if line.strip():
+            para.append((n, line))
+        else:
+            flush()
+    flush()
+    return out
+
+
+def next_command(root):
+    p = os.path.join(root, "PROJECT-STATUS.md")
+    if not os.path.isfile(p):
+        return ""
+    m = re.search(r"(?ms)^##\s+Next command to run.*?```[^\n]*\n(.*?)```", open(p, encoding="utf-8").read())
+    return m.group(1).strip().splitlines()[0] if m and m.group(1).strip() else ""
+
+
+def check(text, label, root, final=False, words=None, ups=None):
+    fails = []
+    fail = lambda n, msg: fails.append(f"FAIL {label}{':' + str(n) if n else ''}: {msg}")
+    words = load_words(root) if words is None else words
+    ups = upstream_state(root) if ups is None else ups
+    prose, fenced = split_text(text)
+
+    # 1. words
+    seen = set()
+    for n, line in prose:
+        plain = re.sub(r"`[^`]*`", " ", re.sub(r"https?://\S+|\]\([^)]*\)", " ", line))
+        plain = re.sub(r'"[^"\n]{1,30}"|“[^”\n]{1,30}”', " ", plain)   # a word quoted to name it is not used
+        for w, say in words.items():
+            if w not in seen and re.search(rf"(?i)(?<![\w-]){re.escape(w)}s?(?![\w-])", plain):
+                seen.add(w)
+                fail(n, f'"{w}" is a word the owner has to look up; say "{say}"')
+        for name in SCRIPT_NAME.findall(re.sub(r"https?://\S+|\]\([^)]*\)", " ", line)):
+            if name not in seen:
+                seen.add(name)
+                fail(n, f'"{name}" is a name inside a script; say in words what it is')
+
+    # 2. upstream problems. A fixed or closed one must read as such wherever it is named; an open
+    # one must be explained once, in a table row saying what it affects and whether it blocks or
+    # breaks anything, and must appear in the prompt that gets it fixed.
+    us = units(prose)
+    mentions = {}
+    for n, txt, header in us:
+        for rid in dict.fromkeys(ANY_ID.findall(txt)):
+            if rid in ups:
+                mentions.setdefault(rid, []).append((n, txt, header))
+    for rid, ms in sorted(mentions.items(), key=lambda kv: kv[1][0][0]):
+        st, where = ups[rid]
+        if st in ("fixed", "closed"):
+            # read the sentence that names it, or its table row: "TF-901 is filed. X is fixed." is wrong
+            said = lambda txt, h: [txt] if h is not None else [s for s in re.split(r"(?<=[.!?])\s+", txt) if rid in s]
+            wrong = next((n for n, txt, h in ms
+                          if not all(re.search(r"(?i)\b(fixed|closed)\b", s) for s in said(txt, h))), None)
+            if wrong is not None:
+                fail(wrong, f"{rid} is written about as an open problem, but {where} records it as "
+                            f"{'fixed upstream' if st == 'fixed' else 'closed'}; say so, and say what re-checks it here")
+            continue
+        explained = any(h is not None and "affect" in h.lower() and re.search(r"(?i)block|break", h)
+                        for _n, _t, h in ms)
+        if not explained:
+            fail(ms[0][0], f"{rid} is named without saying what it affects and whether it blocks or breaks "
+                           f"anything: put it in a table with the columns Problem | What it affects | Does it block or break anything")
+        elif not re.search(rf"(?<![\w-]){re.escape(rid)}\b", fenced):
+            fail(ms[0][0], f"{rid} is open and no code block gives the prompt that gets it fixed")
+
+    # 3. commands: one presented as something to run needs the line to paste. Naming a command
+    # to say what it did ("*build-phase means build every unfinished row") needs nothing.
+    known = COMMANDS | {os.path.splitext(os.path.basename(p))[0]
+                        for p in glob.glob(os.path.join(root, ".tfcore", "tasks", "*.md"))
+                        if not os.path.basename(p).startswith("_")}
+    named = {}
+    for n, txt, _h in us:
+        plain = re.sub(r"`[^`]*`", " ", txt)                 # `run-void` is a name, not a cue
+        plain = re.sub(r"(?i)\b(?:do not|don't|never|no need to|need not)\s+run\b", " ", plain)
+        if not TO_RUN.search(plain):
+            continue
+        for c in COMMAND.findall(txt):
+            if c in known:
+                named.setdefault(c, n)
+    for c, n in sorted(named.items(), key=lambda kv: kv[1]):
+        if not re.search(rf"\*{re.escape(c)}\b", fenced):
+            fail(n, f"*{c} is named, but no code block holds the line to paste for it "
+                    f"(tf-status-facts.sh prints it in both harness forms)")
+
+    # 4. a command's closing message ends by handing over the next prompt
+    if final and not fenced.strip():
+        nc = next_command(root)
+        fail(0, "the closing message gives no next prompt; end with a code block holding the line to paste"
+                + (f" — PROJECT-STATUS.md says: {nc}" if nc else ""))
+    return fails
+
+
+def main(argv):
+    root, final, stdin, files = os.getcwd(), False, False, []
+    it = iter(argv)
+    for a in it:
+        if a == "--root":
+            root = os.path.abspath(next(it, "."))
+        elif a == "--final":
+            final = True
+        elif a == "--stdin":
+            stdin = True
+        elif a in ("-h", "--help"):
+            print(__doc__)
+            return 0
+        else:
+            files.append(a)
+    if not stdin and not files:
+        print(__doc__)
+        return 2
+    words, ups, fails, checked = load_words(root), upstream_state(root), [], 0
+    if stdin:
+        fails += check(sys.stdin.read(), "the closing message", root, final, words, ups)
+        checked += 1
+    for f in files:
+        rel = os.path.relpath(os.path.abspath(f), root)
+        if TEMPLATED.search(rel.replace("\\", "/")):
+            print(f"SKIP {rel}: it has a template; tf-doc-check.sh checks it")
+            continue
+        if not os.path.isfile(f):
+            fails.append(f"FAIL {rel}: file not found")
+            continue
+        # a document handed over is held to the first three checks; ending on the next prompt is
+        # the closing message's job
+        fails += check(open(f, encoding="utf-8", errors="replace").read(), rel, root, False, words, ups)
+        checked += 1
+    for line in fails:
+        print(line)
+    print(f"tf-owner-text: {len(fails)} FAIL in {checked} text(s)")
+    return 1 if fails else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/.tfcore/utils/tf-owner-text.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# tf-owner-text.sh — check text written for the owner: plain words, every upstream problem with
+# what it affects and the prompt that fixes it, every named command with the line to paste, and
+# a command's closing message ending on the next prompt (MISS-TechieFlow-20260911-03).
+#
+#   bash .tfcore/utils/tf-owner-text.sh [--root <dir>] [--final] <file> ...
+#   printf '%s' "<message>" | bash .tfcore/utils/tf-owner-text.sh --final --stdin
+#
+# The Stop hook runs it on a command's closing message and on every free-form document that
+# message hands the owner. Details: tf-owner-text.py. Exit 0 clean, 1 a FAIL, 2 could not run.
+set -u
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+command -v python3 >/dev/null 2>&1 || { echo "tf-owner-text: python3 is required" >&2; exit 2; }
+exec python3 "$HERE/tf-owner-text.py" "$@"

package/.tfcore/utils/tf-phase.sh

@@ -38,17 +38,48 @@ case "${1:-}" in
       NOW="$(sed -n 's/.*"started":"\([^"]*\)".*/\1/p' "$FILE")"
       echo "tf-phase: started taken from the supervisor's marker ($NOW)" >&2
     fi
-    printf '{"cmd":"%s","app":"%s","started":"%s"}\n' "$CMD" "$APP" "$NOW" > "$FILE"
+    # A command started inside another one (*fix-issues and *build-phase run *verify inline) keeps
+    # the outer command as "outer", written FIRST so a greedy `.*"started":"…"` read still takes this
+    # command's own start. tf-verify-emit.sh and tf-fix-close.sh read it to tell the two starts
+    # apart (TF-052: the inline verify took the fix's start and its record swallowed the fix's).
+    OUTER=""; CHAINED=""
+    if [[ -f "$FILE" && -z "$(find "$FILE" -mmin +1440 2>/dev/null)" ]]; then
+      OC="$(sed -n 's/.*"cmd":"\([^"]*\)".*/\1/p' "$FILE")"; OA="$(sed -n 's/.*"app":"\([^"]*\)".*/\1/p' "$FILE")"
+      OS="$(sed -n 's/.*"started":"\([^"]*\)".*/\1/p' "$FILE")"
+      [[ -n "$OC" && -n "$OS" && "$OC" != "$CMD" && "$OC" != "goal" && "$OS" != "$NOW" ]] \
+        && OUTER="\"outer\":{\"cmd\":\"$OC\",\"app\":\"$OA\",\"started\":\"$OS\"},"
+      # A command the task files run inside another one keeps the outer command's document baseline
+      # (TrBlazeUI TF-002: *triage-and-fix started verify-phase and metrics-report, each wrote a new
+      # baseline, and the rows the triage had just added had their findings relabelled OLD). The pairs
+      # are the chains the task files name: build-phase, fix-issues and triage-and-fix run verify-phase;
+      # triage-and-fix runs metrics-report. The marker is never ended, so a standalone verify after a
+      # fix also keeps the fix's baseline: that can only make the gate stricter, never hide a finding.
+      OOC="$(sed -n 's/^{"outer":{"cmd":"\([^"]*\)".*/\1/p' "$FILE")"
+      case "$CMD" in
+        verify-phase|metrics-report)
+          for c in "$OC" "$OOC"; do
+            case "$c" in build-phase|fix-issues|triage-and-fix) CHAINED="$c"; break ;; esac
+          done ;;
+      esac
+    fi
+    printf '{%s"cmd":"%s","app":"%s","started":"%s"}\n' "$OUTER" "$CMD" "$APP" "$NOW" > "$FILE"
     echo "$NOW"
     echo "tf-phase: $CMD${APP:+ $APP} started $NOW (marker .tfcore/.session/phase.json)" >&2
     # The document-check baseline (Sitting 4c, 2026-09-06): the findings the checklists and the
     # status file already carry when the command starts are recorded, so the gate and the Stop
     # hook block only on findings this command introduces (Schemas §7.1 decision 8: old projects
     # are repaired through *amend-docs, never by whichever command happens to run next).
-    if [[ -x "$ROOT/.tfcore/utils/tf-doc-check.sh" || -f "$ROOT/.tfcore/utils/tf-doc-check.sh" ]]; then
+    if [[ -n "$CHAINED" ]]; then
+      echo "tf-phase: $CMD runs inside $CHAINED — keeping its document baseline (findings since $CHAINED started stay FAIL)" >&2
+    elif [[ -x "$ROOT/.tfcore/utils/tf-doc-check.sh" || -f "$ROOT/.tfcore/utils/tf-doc-check.sh" ]]; then
+      # Every file `tf-doc-check.sh --app` reads, not only the checklists and the status file: *amend-docs
+      # and day-1 close on `--app`, so the BRD's, the Architecture's and the mockups' old findings read
+      # as new and blocked the run (Lekhak TF-023, 131 of them). A baseline only relabels what was
+      # already there, so a finding the command introduces still FAILs.
       docs=(); for f in "$ROOT"/docs/*-Checklist.md "$ROOT"/PROJECT-STATUS.md; do [[ -f "$f" ]] && docs+=("$f"); done
-      if [[ ${#docs[@]} -gt 0 ]]; then
-        ( cd "$ROOT" && bash .tfcore/utils/tf-doc-check.sh --root "$ROOT" --baseline-write "${docs[@]}" 2>/dev/null | tail -1 >&2 ) || true
+      appargs=(); [[ -n "$APP" && -d "$ROOT/docs" ]] && appargs=(--app "$APP")
+      if [[ ${#docs[@]} -gt 0 || ${#appargs[@]} -gt 0 ]]; then
+        ( cd "$ROOT" && bash .tfcore/utils/tf-doc-check.sh --root "$ROOT" --baseline-write ${appargs[@]+"${appargs[@]}"} ${docs[@]+"${docs[@]}"} 2>/dev/null | tail -1 >&2 ) || true
       fi
     fi
     # The framework's own scripts, against THIS project's real files, before the command
@@ -68,6 +99,9 @@ case "${1:-}" in
       else
         echo "tf-phase: framework self-check clean" >&2
       fi
+      # upstream fixes this project has not re-checked: passed through whole, because "clean"
+      # alone let an agent report two fixed problems to the owner as open (2026-09-11)
+      sed -n '/^Fixed upstream, not yet re-checked here/,/tf-feedback.sh <App> --close/p' <<<"$sc" | sed 's/^/tf-phase: /' >&2
     fi
     ;;
   goal)

package/.tfcore/utils/tf-portable.sh

@@ -0,0 +1,230 @@
+# tf-portable.sh — the few commands that differ between Linux/WSL (GNU tools, bash 4+) and a
+# stock Mac (bash 3.2 at /bin/bash, BSD sed/date/stat, no GNU coreutils). Sourced, not run:
+#   source "$(dirname "${BASH_SOURCE[0]}")/tf-portable.sh"
+# Every function uses the native tool when it is there, so Linux and WSL behave exactly as they
+# did before this file existed; the fallback runs only where the native tool is missing.
+# Plain functions only: sourcing it defines functions and nothing else (no variables, no traps,
+# no set options). Bash 3.2 safe. The check tests/portability/run.sh keeps GNU-only and
+# bash-4-only constructs out of every other script; add a function here instead.
+#
+#   tf_timeout DURATION CMD [ARG...]     timeout(1); 124 when the time runs out
+#   tf_setsid [--exec] CMD [ARG...]      setsid(1); --exec replaces the calling (sub)shell
+#   tf_sed_inplace SED-ARG... FILE       sed -i on GNU and BSD sed, no backup file left behind
+#   tf_stat_mtime FILE                   modification time, epoch seconds
+#   tf_stat_size FILE                    size in bytes
+#   tf_date_from [-u] WHEN [+FORMAT]     date -d WHEN; WHEN is @EPOCH, "-10 min", "+2 hours",
+#                                        "now", or YYYY-MM-DD[( |T)HH:MM[:SS]][Z]
+#   tf_epoch_frac                        seconds since the epoch with a fraction (date +%s.%N)
+#   tf_realpath PATH                     realpath(1) as GNU has it (the last part may be missing)
+#   tf_relpath BASE PATH                 realpath --relative-to=BASE PATH
+#   tf_read_lines ARRAY-NAME             mapfile -t ARRAY-NAME (reads stdin)
+
+# ---- tf_timeout ---------------------------------------------------------------------------
+# GNU timeout, then Homebrew's gtimeout, then a perl fallback (perl ships with macOS). The
+# fallback runs the command in its own process group, sends the group TERM when the time is up
+# and exits 124, the code timeout(1) uses; otherwise it exits with the command's own status
+# (128+N when signal N ended it), and 126/127 when the command cannot be run, as timeout(1) does.
+tf_timeout() {
+  if [ $# -lt 2 ]; then echo "tf_timeout: usage: tf_timeout DURATION COMMAND [ARG...]" >&2; return 125; fi
+  if command -v timeout >/dev/null 2>&1; then timeout "$@"; return $?; fi
+  if command -v gtimeout >/dev/null 2>&1; then gtimeout "$@"; return $?; fi
+  _tf_timeout_perl "$@"
+}
+_tf_timeout_perl() {
+  local dur="$1" secs; shift
+  case "$dur" in
+    *s) secs="${dur%s}" ;;
+    *m) secs="$(awk -v n="${dur%m}" 'BEGIN { print n * 60 }')" ;;
+    *h) secs="$(awk -v n="${dur%h}" 'BEGIN { print n * 3600 }')" ;;
+    *d) secs="$(awk -v n="${dur%d}" 'BEGIN { print n * 86400 }')" ;;
+    *) secs="$dur" ;;
+  esac
+  case "$secs" in ''|*[!0-9.]*) echo "tf_timeout: invalid time interval '$dur'" >&2; return 125 ;; esac
+  perl -e '
+    use strict; use POSIX ();
+    my $secs = shift @ARGV;
+    my $pid = fork();
+    if (!defined $pid) { print STDERR "tf_timeout: fork failed: $!\n"; exit 125; }
+    if ($pid == 0) {
+      setpgrp(0, 0);   # its own process group, so the whole tree is stopped, as timeout(1) does
+      exec { $ARGV[0] } @ARGV;
+      my $code = $!{ENOENT} ? 127 : 126;
+      print STDERR "tf_timeout: failed to run command \x27$ARGV[0]\x27: $!\n";
+      POSIX::_exit($code);
+    }
+    my $fired = 0;
+    $SIG{ALRM} = sub { $fired = 1; kill("TERM", -$pid) or kill("TERM", $pid); };
+    $SIG{TERM} = sub { kill "TERM", $pid; };
+    $SIG{INT}  = sub { kill "INT", $pid; };
+    if ($secs > 0) {
+      my $whole = int($secs); $whole++ if $whole < $secs;   # alarm takes whole seconds; round up
+      alarm($whole);
+    }
+    my $got;
+    do { $got = waitpid($pid, 0); } while ($got == -1 && $!{EINTR});
+    my $status = $?;
+    alarm(0);
+    exit 124 if $fired;
+    exit(128 + ($status & 127)) if $status & 127;
+    exit($status >> 8);
+  ' "$secs" "$@"
+}
+
+# ---- tf_setsid ----------------------------------------------------------------------------
+# util-linux setsid, then python3 os.setsid, then perl POSIX::setsid. As setsid(1) does, a
+# caller that already leads a process group is forked first and the parent returns 0 at once.
+# --exec: replace the calling (sub)shell with it, like `exec setsid CMD`.
+tf_setsid() {
+  local ex=""
+  if [ "${1:-}" = "--exec" ]; then ex=exec; shift; fi
+  if [ $# -lt 1 ]; then echo "tf_setsid: usage: tf_setsid [--exec] COMMAND [ARG...]" >&2; return 1; fi
+  if command -v setsid >/dev/null 2>&1; then $ex setsid "$@"
+  elif command -v python3 >/dev/null 2>&1; then $ex python3 -c "$(_tf_setsid_py)" "$@"
+  elif command -v perl >/dev/null 2>&1; then $ex perl -e "$(_tf_setsid_pl)" "$@"
+  else echo "tf_setsid: needs setsid, python3 or perl; none is on PATH" >&2; return 127
+  fi
+}
+_tf_setsid_py() {
+  printf '%s\n' \
+    'import os, sys' \
+    'if os.getpgrp() == os.getpid():' \
+    '    if os.fork() != 0:' \
+    '        os._exit(0)' \
+    'os.setsid()' \
+    'try:' \
+    '    os.execvp(sys.argv[1], sys.argv[1:])' \
+    'except OSError as e:' \
+    '    sys.stderr.write("setsid: failed to execute %s: %s\n" % (sys.argv[1], e.strerror))' \
+    '    os._exit(127 if e.errno == 2 else 126)'
+}
+_tf_setsid_pl() {
+  printf '%s\n' \
+    'use POSIX ();' \
+    'if (getpgrp() == $$) { my $p = fork(); POSIX::_exit(0) if $p; }' \
+    'POSIX::setsid();' \
+    'exec { $ARGV[0] } @ARGV;' \
+    'my $c = $!{ENOENT} ? 127 : 126;' \
+    'print STDERR "setsid: failed to execute $ARGV[0]: $!\n";' \
+    'POSIX::_exit($c);'
+}
+
+# ---- tf_sed_inplace -----------------------------------------------------------------------
+# GNU sed takes -i alone; BSD sed needs -i '' for "no backup". The sed script itself must be
+# one both seds understand (no \s, \+, \n in a replacement, 0,/re/ addresses).
+tf_sed_inplace() {
+  if [ $# -lt 2 ]; then echo "tf_sed_inplace: usage: tf_sed_inplace SED-ARG... FILE" >&2; return 2; fi
+  if sed --version >/dev/null 2>&1; then sed -i "$@"; else sed -i '' "$@"; fi
+}
+
+# ---- tf_stat_mtime / tf_stat_size ---------------------------------------------------------
+tf_stat_mtime() {
+  if stat -c %Y / >/dev/null 2>&1; then stat -c %Y "$1"; else stat -f %m "$1"; fi
+}
+tf_stat_size() {
+  if stat -c %s / >/dev/null 2>&1; then stat -c %s "$1"; else stat -f %z "$1"; fi
+}
+
+# ---- tf_date_from -------------------------------------------------------------------------
+# GNU date reads almost anything with -d; BSD date reads @EPOCH with -r and a fixed layout
+# with -j -f. The WHEN forms listed at the top cover every caller in this framework. On GNU
+# date the WHEN is handed to date -d unchanged, so the output is exactly what it was.
+tf_date_from() {
+  local utc="" when fmt epoch
+  if [ "${1:-}" = "-u" ]; then utc="-u"; shift; fi
+  when="${1:-}"; fmt="${2:-}"
+  if [ -z "$when" ]; then echo "tf_date_from: usage: tf_date_from [-u] WHEN [+FORMAT]" >&2; return 1; fi
+  if date -d @0 +%s >/dev/null 2>&1; then
+    if [ -n "$fmt" ]; then date $utc -d "$when" "$fmt"; else date $utc -d "$when"; fi
+    return $?
+  fi
+  epoch="$(_tf_date_epoch $utc "$when")" || return 1
+  if [ -n "$fmt" ]; then date $utc -r "$epoch" "$fmt"; else date $utc -r "$epoch"; fi
+}
+# WHEN → epoch seconds without GNU date -d. @EPOCH, now and relative offsets are plain
+# arithmetic; an absolute date goes through BSD date -j -f (GNU date on a machine that has it).
+_tf_date_epoch() {
+  local utc="" when now n unit mult value layout
+  if [ "${1:-}" = "-u" ]; then utc="-u"; shift; fi
+  when="$1"; now="$(date +%s)"
+  case "$when" in
+    now) echo "$now"; return 0 ;;
+    @*) echo "${when#@}"; return 0 ;;
+  esac
+  case "$when" in
+    [+-][0-9]*|[0-9]*[a-z]*)
+      n="$(printf '%s' "$when" | sed -E 's/^([+-]?[0-9]+).*/\1/')"
+      unit="$(printf '%s' "$when" | sed -E 's/^[+-]?[0-9]+[[:space:]]*//; s/[[:space:]]*ago$//')"
+      case "$unit" in
+        s|sec|secs|second|seconds) mult=1 ;;
+        min|mins|minute|minutes) mult=60 ;;
+        hour|hours) mult=3600 ;;
+        day|days) mult=86400 ;;
+        week|weeks) mult=604800 ;;
+        *) mult="" ;;
+      esac
+      if [ -n "$mult" ]; then
+        n="${n#+}"
+        case "$when" in *ago) n=$(( -n )) ;; esac
+        echo $(( now + n * mult )); return 0
+      fi ;;
+  esac
+  value="$when"; layout=""
+  case "$value" in *Z) value="${value%Z}"; utc="-u" ;; esac
+  value="$(printf '%s' "$value" | sed 's/T/ /')"
+  case "$value" in
+    [0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]) value="$value 00:00:00" ;;
+    [0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]" "[0-9][0-9]:[0-9][0-9]) value="$value:00" ;;
+  esac
+  case "$value" in
+    [0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]" "[0-9][0-9]:[0-9][0-9]:[0-9][0-9]) layout="%Y-%m-%d %H:%M:%S" ;;
+  esac
+  if [ -z "$layout" ]; then echo "date: invalid date '$when'" >&2; return 1; fi
+  if date -d @0 +%s >/dev/null 2>&1; then date $utc -d "$value" +%s; else date $utc -j -f "$layout" "$value" +%s; fi
+}
+
+# ---- tf_epoch_frac ------------------------------------------------------------------------
+# GNU date +%s.%N; BSD date prints a literal N, so the fallback asks perl or python3.
+tf_epoch_frac() {
+  local v
+  v="$(date +%s.%N 2>/dev/null)"
+  case "$v" in *N|'') ;; *) printf '%s\n' "$v"; return 0 ;; esac
+  if command -v perl >/dev/null 2>&1; then perl -MTime::HiRes=time -e 'printf("%.9f\n", time)'
+  else python3 -c 'import time; print("%.9f" % time.time())'
+  fi
+}
+
+# ---- tf_realpath / tf_relpath -------------------------------------------------------------
+tf_realpath() {
+  if [ $# -ne 1 ]; then echo "tf_realpath: usage: tf_realpath PATH" >&2; return 1; fi
+  # GNU realpath (it has -m) only: the macOS 13+ realpath refuses a path whose last part does not
+  # exist yet, which GNU realpath and the fallback below both accept.
+  if realpath -m / >/dev/null 2>&1; then realpath "$1"; return $?; fi
+  python3 -c 'import os, sys
+p = sys.argv[1]
+if not os.path.exists(os.path.dirname(os.path.abspath(p)) or "/"):
+    sys.stderr.write("realpath: %s: No such file or directory\n" % p); sys.exit(1)
+print(os.path.realpath(p))' "$1"
+}
+tf_relpath() {
+  if [ $# -ne 2 ]; then echo "tf_relpath: usage: tf_relpath BASE PATH" >&2; return 1; fi
+  if realpath --relative-to=/ / >/dev/null 2>&1; then realpath --relative-to="$1" "$2"; return $?; fi
+  python3 -c 'import os, sys
+print(os.path.relpath(os.path.realpath(sys.argv[2]), os.path.realpath(sys.argv[1])))' "$1" "$2"
+}
+
+# ---- tf_read_lines ------------------------------------------------------------------------
+# mapfile -t NAME < <(cmd)  becomes  tf_read_lines NAME < <(cmd)
+# One element per line, newline removed, a last line without a newline kept, nothing else
+# touched (leading blanks and backslashes stay). NAME is emptied first, as mapfile does.
+tf_read_lines() {
+  case "${1:-}" in
+    ''|[0-9]*|*[!A-Za-z0-9_]*) echo "tf_read_lines: usage: tf_read_lines ARRAY-NAME < input" >&2; return 2 ;;
+  esac
+  local _tf_rl_line _tf_rl_i=0
+  eval "$1=()"
+  while IFS= read -r _tf_rl_line || [ -n "$_tf_rl_line" ]; do
+    eval "$1[\$_tf_rl_i]=\$_tf_rl_line"
+    _tf_rl_i=$(( _tf_rl_i + 1 ))
+  done
+  return 0
+}