@techierathore/techieflow 1.0.3 → 1.1.0

package/.tfcore/utils/tf-fix-close.sh

@@ -3,21 +3,34 @@
 #
 #   bash .tfcore/utils/tf-fix-close.sh <App> [--started <ISO>] [--reqs REQ-UI-009,REQ-FN-014]
 #                                            [--subagents trblazeui,builder] [--build pass|fail|not-run] [--files N]
+#   bash .tfcore/utils/tf-fix-close.sh <App> --misses MISS-App-20260901-06,MISS-App-20260830-03 \
+#                                            --fix-cmd amend-docs [--verdict Verified]
+#
+# The second form closes misses DIRECTLY, by id, with no checklist row and no verify ledger.
+# It exists because a miss whose deficient artifact is a document is fixed by *amend-docs
+# editing the BRD -- never by the verifier touching a row -- so the row-driven form above can
+# never reach it, and the miss stayed open forever (TF-016). It writes NO run record: the
+# amending command emits its own through the status gate. `fix_cmd: "amend-docs"` was already
+# legal in SCHEMA §5.5.2; only this door was missing.
 #
 # Emits, in this order, through tf-emit.sh only:
 #   1. the fix-issues run record (cmd fix-issues, mode fix, the rows touched) — first, because the
-#      miss-fix records below carry no numbers of their own: the emitter copies this run's token window
-#   2. one miss-fix per row that has an open miss, with verdict_after taken from the verify ledger
-#      docs/.last-verify.json written by the verify the fix chained, mapped to a checklist status (PASS →
-#      Verified; FAIL → FAIL; any other failing verdict or an absent row → Needs re-verify). A row with no open miss is listed,
+#      miss-fix records below carry no numbers of their own: the emitter copies this run's token window.
+#      A run the fix chained (the inline verify) keeps its own record, so the fix is recorded in the gaps
+#      around it; the first gap carries the rows and the fix's start (TF-052).
+#   2. one miss-fix per row that has an open miss, with verdict_after taken from every verify the fix
+#      chained: the gate records written since the fix started, then the ledger docs/.last-verify.json
+#      when it belongs to this fix (PASS → Verified; FAIL → FAIL; any other failing verdict → Needs
+#      re-verify). A row no verify graded gets no miss-fix and is listed. A row with no open miss is listed,
 #      not invented: a fix on a defect nobody logged is a triage gap, so open it first with tf-triage.sh
 #      demote or tf-log-miss.sh, then re-run this.
-# --reqs defaults to every row in the ledger. Telemetry never blocks: refusals are printed, exit 0.
+# --reqs defaults to every row those verifies graded. The start defaults to the fix's marker, or its
+# "outer" entry when a chained verify replaced it. Telemetry never blocks: refusals are printed, exit 0.
 set -u
 HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 [[ $# -ge 1 && "$1" != "-h" && "$1" != "--help" ]] || { sed -n '2,17p' "$0" | sed 's/^# \{0,1\}//'; exit 3; }
 APP="$1"; shift
-STARTED=""; REQS=""; SUBS=""; BUILD="pass"; FILES=""
+STARTED=""; REQS=""; SUBS=""; BUILD="pass"; FILES=""; MISSES=""; FIXCMD="fix-issues"; VERDICT=""
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --started) STARTED="${2:-}"; shift 2 ;;
@@ -25,11 +38,20 @@ while [[ $# -gt 0 ]]; do
     --subagents) SUBS="${2:-}"; shift 2 ;;
     --build) BUILD="${2:-}"; shift 2 ;;
     --files) FILES="${2:-}"; shift 2 ;;
+    --misses) MISSES="${2:-}"; shift 2 ;;
+    --fix-cmd) FIXCMD="${2:-}"; shift 2 ;;
+    --verdict) VERDICT="${2:-}"; shift 2 ;;
     *) echo "tf-fix-close: unknown argument $1" >&2; exit 3 ;;
   esac
 done
-[[ -z "$STARTED" ]] && STARTED="$(bash "$HERE/tf-phase.sh" show 2>/dev/null | sed -n 's/.*"started":"\([^"]*\)".*/\1/p')"
-TF_APP="$APP" TF_STARTED="$STARTED" TF_REQS="$REQS" TF_SUBS="$SUBS" TF_BUILD="$BUILD" TF_FILES="$FILES" TF_EMIT="$HERE/tf-emit.sh" python3 - <<'PY'
+# the fix's start: its own marker, or the "outer" one when a verify it chained has replaced the marker
+[[ -z "$STARTED" ]] && STARTED="$(bash "$HERE/tf-phase.sh" show 2>/dev/null | python3 -c "import json,sys
+try: m=json.load(sys.stdin)
+except Exception: m={}
+o=m.get('outer') or {}
+print(m.get('started','') if m.get('cmd')!='verify-phase' or not o.get('started') else o['started'])" 2>/dev/null)"
+TF_APP="$APP" TF_STARTED="$STARTED" TF_REQS="$REQS" TF_SUBS="$SUBS" TF_BUILD="$BUILD" TF_FILES="$FILES" \
+TF_MISSES="$MISSES" TF_FIXCMD="$FIXCMD" TF_VERDICT="$VERDICT" TF_EMIT="$HERE/tf-emit.sh" python3 - <<'PY'
 import datetime, json, os, subprocess
 EMIT = os.environ["TF_EMIT"]; app = os.environ["TF_APP"]; started = os.environ["TF_STARTED"]
 now = datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
@@ -39,45 +61,105 @@ def emit(stream, rec):
     msg = (p.stdout + p.stderr).strip(); ok = p.returncode == 0 and "refus" not in msg.lower() and "error" not in msg.lower()
     if not ok: print(f"  {stream}: not written — {msg.splitlines()[0][:160] if msg else 'no reason printed'}")
     return ok
+# --- close by miss id (the *amend-docs door) -------------------------------------------
+direct = [m.strip() for m in (os.environ.get("TF_MISSES") or "").split(",") if m.strip()]
+if direct:
+    fix_cmd = os.environ.get("TF_FIXCMD") or "amend-docs"
+    verdict = os.environ.get("TF_VERDICT") or "Verified"
+    closed = 0
+    for mid in direct:
+        fa = q("--next-fix-attempt", mid) or "1"
+        rec = {"kind": "miss-fix", "miss_id": mid, "fix_cmd": fix_cmd,
+               "fix_attempt": int(fa) if fa.isdigit() else 1,
+               "verdict_after": verdict, "reopened": False}
+        if started:
+            rec["fix_run_id"] = started
+        if emit("misses", rec):
+            closed += 1
+    print("%s: %d of %d miss-fix record(s) written (no run record — the amending command emits its own)"
+          % (fix_cmd, closed, len(direct)))
+    raise SystemExit(0)
+
+met = q("--where") or "docs/metrics"
+def jsonl(name):
+    try:
+        for line in open(os.path.join(met, name), encoding="utf-8", errors="replace"):
+            try: yield json.loads(line)
+            except Exception: pass
+    except OSError:
+        return
+# The verdicts: every verify this fix chained, not only the last. docs/.last-verify.json holds one scoped
+# verify, so a fix that verified a Phase 3 scope and then a --phase 1 scope read the Phase 3 rows as absent
+# and wrote Needs re-verify on their misses (TF-052). The gate records each verify wrote since the fix
+# started come first; the ledger fills in only when it belongs to this fix.
+rows = {}   # rid -> checklist status
+if started:
+    for g in jsonl("gates.jsonl"):
+        if g.get("kind") == "gate" and g.get("app") in (None, app) and not g.get("backfilled") and g.get("gate") != "escaped" \
+                and (g.get("run_id") or "") >= started and g.get("req_id"):
+            rows[g["req_id"].upper()] = g.get("verdict")
 ledger = {}
 try:
     ledger = json.load(open(os.path.join("docs", ".last-verify.json"), encoding="utf-8"))
 except Exception:
     pass
-rows = ledger.get("rows") or {}
+if not started or not ledger.get("run_id") or ledger["run_id"] >= started:
+    row_runs = ledger.get("row_runs")   # a ledger kept row by row also holds older runs' rows (Lekhak TF-007)
+    for rid, v in (ledger.get("rows") or {}).items():
+        if started and isinstance(row_runs, dict) and rid not in (ledger.get("this_run") or []) \
+                and (row_runs.get(rid) or "") < started:
+            continue
+        # verdict_after takes a checklist status (SCHEMA §5.5): the ledger's verdict is mapped, never passed raw
+        # (MISS-TechieFlow-20260906-25: RENDER-FAIL was refused and twenty miss-fix records never landed)
+        rows.setdefault(rid.upper(), "Verified" if v == "PASS" else "FAIL" if v in ("FAIL", "BUILD-FAIL") else "Needs re-verify")
 reqs = [r.strip().upper() for r in os.environ["TF_REQS"].split(",") if r.strip()] or sorted(rows)
 subs = [s.strip() for s in os.environ["TF_SUBS"].split(",") if s.strip()]
 files = os.environ["TF_FILES"]
-run = {"kind": "run", "app": app, "cmd": "fix-issues", "mode": "fix", "ended": now, "reqs_touched": reqs, "reqs_count": len(reqs),
-       "subagents": subs, "files_written": int(files) if files.isdigit() else len(reqs), "build_result": os.environ["TF_BUILD"]}
-if started: run["started"] = started
-# one run record per start: a close called twice must not count the fix twice
-runs_path = os.path.join(q("--where") or "docs/metrics", "runs.jsonl")
-already = False
-if started and os.path.isfile(runs_path):
-    for line in open(runs_path, encoding="utf-8", errors="replace"):
-        if '"cmd":"fix-issues"' in line and f'"started":"{started}"' in line:
-            already = True
-            break
-ok = True if already else emit("runs", run)
-if already:
-    print(f"fix-issues: run record for start {started} already exists; not written again")
-closed, none = 0, []
+# The fix's own time only: a run it chained (the inline verify) has its own record, so the fix is recorded
+# in the gaps around it, the first gap keyed on the fix's start with the rows (its miss-fixes name that start).
+inner, voided = [], set()
+for r in jsonl("runs.jsonl"):
+    if r.get("kind") == "run-void":
+        voided.add((r.get("cmd"), r.get("started")))
+    elif r.get("kind", "run") == "run" and r.get("app") == app and r.get("cmd") != "fix-issues" and not r.get("backfilled") \
+            and started and (r.get("started") or "") >= started and (r.get("ended") or "") and r["ended"] <= now:
+        inner.append((r["started"], r["ended"], r.get("cmd")))
+inner = sorted(w for w in inner if (w[2], w[0]) not in voided)
+gaps, t = [], started
+for s, e, _c in inner:
+    if t and s > t: gaps.append((t, s))
+    t = max(t, e) if t else e
+if not started or not gaps or t < now: gaps.append((t, now))
+existing = {r.get("started") for r in jsonl("runs.jsonl") if r.get("kind", "run") == "run" and r.get("cmd") == "fix-issues"}
+wrote = had = 0
+for i, (s, e) in enumerate(gaps):
+    first = i == 0
+    run = {"kind": "run", "app": app, "cmd": "fix-issues", "mode": "fix", "ended": e, "reqs_touched": reqs if first else [],
+           "reqs_count": len(reqs) if first else 0, "subagents": subs if first else [],
+           "files_written": (int(files) if files.isdigit() else len(reqs)) if first else 0, "build_result": os.environ["TF_BUILD"]}
+    if s: run["started"] = s
+    # one run record per start: a close called twice must not count the fix twice
+    if s and s in existing:
+        had += 1; continue
+    wrote += emit("runs", run)
+if inner:
+    print(f"fix-issues: recorded around {len(inner)} chained run(s) ({', '.join(sorted({c for _s, _e, c in inner}))}) in {len(gaps)} segment(s)")
+closed, none, unverified = 0, [], []
 for rid in reqs:
+    if rid not in rows:
+        unverified.append(rid); continue
     opened = q("--open-miss", rid)
     if not opened:
         none.append(rid); continue
     mid = opened.split()[0]
     fa = q("--next-fix-attempt", mid) or "1"
-    v = rows.get(rid)
-    # verdict_after takes a checklist status (SCHEMA §5.5): the ledger's verdict is mapped, never passed raw
-    # (MISS-TechieFlow-20260906-25: RENDER-FAIL was refused and twenty miss-fix records never landed)
-    after = ("Verified" if v == "PASS" else "FAIL" if v in ("FAIL", "BUILD-FAIL") else "Needs re-verify")
     rec = {"kind": "miss-fix", "miss_id": mid, "req_id": rid, "fix_cmd": "fix-issues", "fix_attempt": int(fa) if fa.isdigit() else 1,
-           "verdict_after": after, "reopened": False}
+           "verdict_after": rows[rid], "reopened": False}
     if started: rec["fix_run_id"] = started
     if emit("misses", rec): closed += 1
-print(f"fix-issues: run record {'already there' if already else 'written' if ok else 'not written'}; {closed} miss-fix record(s) with the verifier's verdict"
-      + (f"; no open miss on {', '.join(none)} (log it first, then re-run)" if none else ""))
+state = "already there" if had == len(gaps) else "written" if wrote + had == len(gaps) else "not written"
+print(f"fix-issues: run record {state}; {closed} miss-fix record(s) with the verifier's verdict"
+      + (f"; no open miss on {', '.join(none)} (log it first, then re-run)" if none else "")
+      + (f"; no verify graded {', '.join(unverified)} during this fix, so its miss stays open with no miss-fix" if unverified else ""))
 PY
 exit 0

package/.tfcore/utils/tf-gitignore-audit.sh

@@ -74,7 +74,7 @@ DRY  = os.environ["TF_DRY"] == "1"
 # ones this audit exists to catch. The file system is the fact.
 STACKS = [
     ("dotnet", (".csproj", ".fsproj", ".vbproj", ".sln", ".slnx"),
-     ["bin/", "obj/", "*.user", "TestResults/"]),
+     ["bin/", "obj/", "*.user", "TestResults/", ".vs/"]),
     ("node",   ("package.json",),        ["dist/", "build/", ".next/", ".nuxt/", ".turbo/"]),
     ("python", ("pyproject.toml", "setup.py", "requirements.txt"),
      ["__pycache__/", "*.py[cod]", ".venv/", "venv/", ".pytest_cache/", "*.egg-info/"]),
@@ -83,6 +83,14 @@ STACKS = [
     ("java",   ("pom.xml", "build.gradle", "build.gradle.kts"), ["target/", "build/", ".gradle/"]),
 ]
 
+# Per-developer IDE state, wanted whatever the stack is. It is not build output, but it is
+# the same harm and this tool is the only thing looking: TfLens tracked three .bin files
+# under .vs/ProjectEvaluation/, one carrying 246 absolute paths out of one developer's
+# machine, while the audit ran on that repo every week and said nothing. `.vscode/` is NOT
+# here -- a team often commits it deliberately, and a rule that fights the owner gets
+# switched off. tests/regression/run.sh tf_014.
+IDE_STATE = [".vs/", ".idea/"]
+
 # `package.json` alone does NOT make a repo a Node project, and this exception is
 # load-bearing rather than fussy: verify-phase §1 runs `npm init -y` in EVERY repo
 # to provision Playwright, so a bare package.json sits in essentially every .NET
@@ -114,14 +122,19 @@ def _is_real_node(root, files):
     # `npm init -y` writes exactly one script: a `test` stub that echoes and exits 1.
     return any(k in scripts for k in ("build", "dist", "bundle", "compile"))
 
+# A NAME list, never a blanket dot-rule. `not d.startswith(".")` used to prune every
+# dot-directory from the walk -- .vs/, .idea/, .gradle/, .terraform/, .pytest_cache/ --
+# which is close to a complete list of the per-developer state a gitignore audit is FOR.
+# The tool cannot report a folder it never visits, and its silence read exactly like a pass.
 SKIP_DIRS = {".git", "node_modules", ".tfcore", "bin", "obj", "target", "dist",
-             "build", ".venv", "venv", "__pycache__", ".next"}
+             "build", ".venv", "venv", "__pycache__", ".next", ".claude", ".opencode",
+             ".vscode", ".github", ".husky", ".yarn"}
 
 
 def detect():
     found = set()
     for root, dirs, files in os.walk(REPO):
-        dirs[:] = [d for d in dirs if d not in SKIP_DIRS and not d.startswith(".")]
+        dirs[:] = [d for d in dirs if d not in SKIP_DIRS]
         if root.count(os.sep) - REPO.count(os.sep) > 3:
             dirs[:] = []
         for name, markers, _ in STACKS:
@@ -154,6 +167,24 @@ def covered(rule, lines):
     return False
 
 
+def child_only_rules(rule, lines):
+    """Rules that ignore something INSIDE `rule` while `rule` itself stays open.
+
+    This shape is more dangerous than no rule at all, because it looks deliberate:
+    TfLens carried `/.vs/App.slnx`, which covers the solution-named subfolder and
+    leaves `.vs/ProjectEvaluation/` tracked. The next folder the IDE creates is not
+    covered either, and nobody re-reads a line that already mentions the directory."""
+    core = rule.strip("/*").rstrip("/")
+    out = []
+    for l in lines:
+        if not l or l.startswith("#"):
+            continue
+        c = l.lstrip("!").strip().replace("**/", "").strip("/")
+        if c != core and (c.startswith(core + "/") or c.startswith(core + "\\")):
+            out.append(l.strip())
+    return out
+
+
 def tracked_paths():
     """Read .git/index directly. Returns the set of tracked paths, or None when the
     index cannot be read (a bare repo, a worktree file, a version we do not know) —
@@ -210,8 +241,18 @@ wanted = []
 for name, _, rules in STACKS:
     if name in stacks:
         wanted += [(name, r) for r in rules]
+if stacks:
+    wanted += [("ide", r) for r in IDE_STATE if not any(r == w for _n, w in wanted)]
 
 missing = [(s, r) for s, r in wanted if not covered(r, lines)]
+# A rule naming a child of a directory that is itself unignored: report it separately,
+# because "MISSING .vs/" reads like nobody thought about it when in fact somebody did
+# and got it half right, which is the harder thing to spot in a review.
+half_done = []
+for _s, r in missing:
+    kids = child_only_rules(r, lines)
+    if kids:
+        half_done.append((r, kids))
 
 tracked = tracked_paths()
 offenders = {}
@@ -244,6 +285,12 @@ else:
         print("    ⚠ MISSING build-output rules: %s" % names)
         print("      add them with: bash .tfcore/utils/tf-gitignore-audit.sh . --fix")
 
+for r, kids in half_done:
+    rc |= 1
+    print("    ⚠ %s is not ignored, but %s covers a child of it — the parent is open"
+          % (r, ", ".join(kids)))
+    print("      a rule on a child looks deliberate and leaves every sibling tracked")
+
 if tracked is None:
     print("    tracked-file check skipped (no readable .git/index) — rules alone do not")
     print("    prove build output is untracked; re-run where the index is readable")

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

@@ -2,9 +2,9 @@
 # tf-goal.sh — unattended GOAL runner / supervisor for TechieFlow (rule: .tfcore/tasks/_yolo-mode.md)
 #
 # Runs a goal headless in YOLO mode and keeps it running until the agent itself
-# declares the goal done — surviving the subscription 5-hour / weekly usage
-# limits (sleeps until the stated reset + a buffer, then RESUMES THE SAME
-# SESSION), crashes, and "I stopped early to ask you something" turns.
+# declares the goal done — surviving the subscription 5-hour / weekly usage limits (moves to the
+# next model in the tier's fallback chain, or sleeps until the stated reset + a buffer when there
+# is none, then RESUMES THE SAME SESSION), crashes, and "I stopped early to ask you something".
 #
 #   bash .tfcore/utils/tf-goal.sh [options] <app-dir> "<goal text>"
 #   bash .tfcore/utils/tf-goal.sh [options] <app-dir> @goal.md
@@ -12,6 +12,10 @@
 # Options
 #   --harness claude|opencode   default: claude
 #   --model <id>                claude: --model; opencode: -m
+#   --tier <tier>               which routing tier this run belongs to, for the fallback chain
+#                               (default standard) — .tfcore/routing.yaml `fallbacks:`
+#   --no-fallback               never switch model on a usage limit; sleep until the reset instead
+#                               (the behaviour before 2026-09-10)
 #   --buffer-min <n>            minutes added after a stated limit-reset time (default 15)
 #   --probe-min <n>             limit hit but NO reset time parseable → fire a one-turn probe every n
 #                               minutes until the API answers again, then resume (default 15)
@@ -41,6 +45,14 @@
 #   goal.log         everything the harness printed, all cycles, timestamped
 #   goal-done.json   the agent's completion sentinel (tf-yolo.sh done [complete|blocked])
 #
+# WHEN A MODEL RUNS OUT (added 2026-09-10, MISS-TechieFlow-20260910-01). A usage limit used to mean
+# one thing: sleep until the reset. It now means: park that model in the per-machine cooldown file
+# (tf-model-pick.sh), ask the tier for the next model in its `fallbacks:` chain, re-bind so the
+# sub-agents move too, and start the next cycle straight away on that model. Only when the whole
+# chain is parked does the supervisor sleep, exactly as before. If the fallback is limited as well
+# the next cycle parks that one too, so an account-wide limit — every Claude model at once — costs
+# one wasted cycle and then behaves as it always did. `--no-fallback` turns all of it off.
+#
 # How the agent is told to finish: the prompt preamble (below) instructs it to run
 # `bash .tfcore/utils/tf-yolo.sh done complete "<summary>"` when the goal is met,
 # or `... done blocked "<why>"` when only the owner can unblock it. A cycle that
@@ -56,14 +68,19 @@
 #   Override command lines with TF_GOAL_CLAUDE_FLAGS / TF_GOAL_OPENCODE_FLAGS /
 
 set -u
+# GNU-only commands (setsid, stat -c, date -d) go through the shim, so a stock Mac runs this too.
+source "$(dirname "${BASH_SOURCE[0]}")/tf-portable.sh"
 
 HARNESS="claude"; MODEL=""; BUFFER_MIN=15; DEFAULT_WAIT_MIN=60; MAX_CYCLES=60; IDLE_RETRY=30
 PROBE_MIN=15; PROBE_MAX_H=8; STALL_MIN=15
+TIER="standard"; FALLBACK=1
 RESUME=0; FRESH=0; DRY=0
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --harness) HARNESS="$2"; shift 2 ;;
     --model) MODEL="$2"; shift 2 ;;
+    --tier) TIER="$2"; shift 2 ;;
+    --no-fallback) FALLBACK=0; shift ;;
     --buffer-min) BUFFER_MIN="$2"; shift 2 ;;
     --default-wait-min) DEFAULT_WAIT_MIN="$2"; shift 2 ;;
     --probe-min) PROBE_MIN="$2"; shift 2 ;;
@@ -74,7 +91,7 @@ while [[ $# -gt 0 ]]; do
     --resume) RESUME=1; shift ;;
     --fresh) FRESH=1; shift ;;
     --dry-run) DRY=1; shift ;;
-    -h|--help) sed -n '2,45p' "$0"; exit 0 ;;
+    -h|--help) sed -n '2,48p' "$0"; exit 0 ;;
     --) shift; break ;;
     -*) echo "unknown option $1" >&2; exit 2 ;;
     *) break ;;
@@ -88,11 +105,15 @@ fi
 APP_DIR="$(cd "$APP_DIR" 2>/dev/null && pwd)" || { echo "no such dir: $1" >&2; exit 2; }
 [[ -d "$APP_DIR/.tfcore" ]] || { echo "$APP_DIR has no .tfcore/ — scaffold it first" >&2; exit 2; }
 case "$HARNESS" in claude|opencode) ;; *) echo "--harness must be claude|opencode" >&2; exit 2 ;; esac
+case "$TIER" in frontier|standard|economy) ;; *) echo "--tier must be frontier|standard|economy" >&2; exit 2 ;; esac
 command -v python3 >/dev/null 2>&1 || { echo "python3 is required" >&2; exit 2; }
 
 STATE_DIR="$APP_DIR/.tfcore/.session"; mkdir -p "$STATE_DIR"
 STATE="$STATE_DIR/goal.json"; LOG="$STATE_DIR/goal.log"; DONE="$STATE_DIR/goal-done.json"
 YOLO_SH="$APP_DIR/.tfcore/utils/tf-yolo.sh"
+PICK_SH="$APP_DIR/.tfcore/utils/tf-model-pick.sh"
+BIND_SH="$APP_DIR/.tfcore/utils/tf-routing-bind.sh"
+[[ -f "$PICK_SH" ]] || FALLBACK=0   # a project that predates tf-model-pick.sh keeps the old behaviour
 
 if [[ "$GOAL_ARG" == @* ]]; then
   GOAL_FILE="${GOAL_ARG#@}"; [[ -f "$GOAL_FILE" ]] || { echo "goal file not found: $GOAL_FILE" >&2; exit 2; }
@@ -126,6 +147,10 @@ if [[ $RESUME -eq 1 ]]; then
   [[ -f "$STATE" ]] || { echo "--resume: no $STATE" >&2; exit 2; }
   [[ -z "$GOAL" ]] && GOAL="$(state_get goal)"
   HARNESS="$(state_get harness)"; HARNESS="${HARNESS:-claude}"
+  # A resume keeps the model a fallback moved to, and the tier its chain came from; an explicit
+  # --model on the resume command still wins.
+  _t="$(state_get tier)"; [[ -n "$_t" ]] && TIER="$_t"
+  _m="$(state_get model)"; [[ -n "$_m" && -z "$MODEL" ]] && MODEL="$_m"
   CYCLE="$(state_get cycle)"; CYCLE="${CYCLE:-0}"
   SESSION_ID="$(state_get session_id)"
   STALLS="$(state_get stalls)"; STALLS="${STALLS:-0}"
@@ -139,12 +164,12 @@ else
     _lr="$(state_get last_reason)"
     case "$_lr" in
       done:*|max-cycles|stopped|"") ;;
-      *) echo "tf-goal: a run looks active in $APP_DIR (goal.json last_reason=$_lr, touched $(date -u -r "$STATE" +%H:%MZ)). Wait for it, or continue it with --resume." >&2; exit 2 ;;
+      *) echo "tf-goal: a run looks active in $APP_DIR (goal.json last_reason=$_lr, touched $(tf_date_from -u "@$(tf_stat_mtime "$STATE")" +%H:%MZ)). Wait for it, or continue it with --resume." >&2; exit 2 ;;
     esac
   fi
   CYCLE=0; SESSION_ID=""; STALLS=0
   if [[ $DRY -eq 0 ]]; then   # a dry run touches nothing: no state, no flag, no log line
-    state_set goal "$GOAL" harness "$HARNESS" cycle 0 session_id "" stalls 0 started "$(ts)" last_reason "start"
+    state_set goal "$GOAL" harness "$HARNESS" tier "$TIER" model "$MODEL" cycle 0 session_id "" stalls 0 started "$(ts)" last_reason "start"
     rm -f "$DONE"
   fi
 fi
@@ -346,6 +371,60 @@ print(sid)
 PY
 }
 
+extract_model() { # the model the harness reported for this cycle, from its own output
+  python3 - "$1" <<'PY' 2>/dev/null
+import sys, json, re
+m = ""
+try:
+    for line in open(sys.argv[1], errors="replace"):
+        line = line.strip()
+        if not line.startswith("{") or '"model"' not in line:
+            continue
+        try: d = json.loads(line)
+        except Exception: continue
+        if not isinstance(d, dict): continue
+        if isinstance(d.get("model"), str) and d["model"]:
+            m = d["model"]
+        msg = d.get("message")
+        if isinstance(msg, dict) and isinstance(msg.get("model"), str) and msg["model"]:
+            m = msg["model"]
+except Exception:
+    pass
+print(m)
+PY
+}
+
+# Park the model this cycle ran on and move to the next one in its tier. Prints nothing and
+# returns 1 when there is nowhere to go — the caller then sleeps, which is what it always did.
+#   $1 = epoch the limit is stated to reset at (or empty when it could not be parsed)
+#   $2 = why, for the cooldown record
+try_fallback() {
+  [[ $FALLBACK -eq 1 ]] || return 1
+  local until="${1:-}" why="${2:-usage limit}" cur next
+  cur="$MODEL"
+  [[ -z "$cur" ]] && cur="$(extract_model "$OUT")"
+  if [[ -z "$cur" ]]; then
+    cur="$(TF_PROJECT_DIR="$APP_DIR" bash "$PICK_SH" pick "$TIER" "$HARNESS" 2>/dev/null | tail -1)"
+    [[ "$cur" == inherit ]] && cur=""
+  fi
+  if [[ -z "$cur" ]]; then
+    log "no fallback: nothing here says which model this cycle ran on (no --model, no model id in the output, no routing answer for tier $TIER)"
+    return 1
+  fi
+  [[ -z "$until" ]] && until="probe"
+  TF_PROJECT_DIR="$APP_DIR" bash "$PICK_SH" cooldown "$HARNESS" "$cur" "$until" "$why" >>"$LOG" 2>&1
+  next="$(TF_PROJECT_DIR="$APP_DIR" bash "$PICK_SH" pick "$TIER" "$HARNESS" 2>/dev/null | tail -1)"
+  if [[ -z "$next" || "$next" == "inherit" ]]; then
+    log "no fallback left: every model in the $TIER chain is on cooldown — waiting for the reset instead"
+    return 1
+  fi
+  MODEL="$next"
+  state_set model "$MODEL" fallback_from "$cur" last_reason "fallback:$cur->$MODEL"
+  log "FALLBACK: $cur is limited ($why) — the next cycle runs on $MODEL (tier $TIER). Re-binding so the sub-agents move too."
+  [[ -f "$BIND_SH" ]] && bash "$BIND_SH" "$APP_DIR" 2>&1 | sed 's/^/    /' | tee -a "$LOG" >&2
+  return 0
+}
+
 # Fallback when a limit message carries no parseable reset time: fire a one-turn
 # probe every PROBE_MIN minutes until it comes back clean (exit 0 AND no limit
 # wording in its output). Gives up after PROBE_MAX_H hours and resumes anyway.
@@ -359,11 +438,11 @@ probe_until_clear() {
     else
       ( cd "$APP_DIR" && opencode run --auto "Reply with the single word OK." ) > "$pout" 2>&1; prc=$?
     fi
-    if [[ $prc -eq 0 ]] && ! grep -qiE 'usage limit|hit your limit|rate[ _-]?limit|limit (has been )?(reached|exceeded)|too many requests|\b429\b|overloaded|weekly limit|resets? (at|in)\b' "$pout"; then
+    if [[ $prc -eq 0 ]] && ! grep -qiE 'usage limit|hit your limit|rate[ _-]?limit|limit (has been )?(reached|exceeded)|too many requests|(^|[^[:alnum:]_])429([^[:alnum:]_]|$)|overloaded|weekly limit|resets? (at|in)([^[:alnum:]_]|$)' "$pout"; then
       log "probe #$n OK"; return 0
     fi
     log "probe #$n still limited (rc=$prc: $(head -c 120 "$pout" | tr '\n' ' ')) — next in ${PROBE_MIN}m"
-    state_set resume_at "probe #$((n+1)) at $(date -d "+${PROBE_MIN} min" '+%H:%M' 2>/dev/null)"
+    state_set resume_at "probe #$((n+1)) at $(tf_date_from "+${PROBE_MIN} min" '+%H:%M' 2>/dev/null)"
     if [[ $(date +%s) -ge $deadline ]]; then log "probe window (${PROBE_MAX_H}h) exhausted — resuming anyway"; return 1; fi
     nap $(( PROBE_MIN * 60 ))
   done
@@ -373,7 +452,7 @@ sleep_until() { # epoch
   local target="$1" now left
   while :; do
     now=$(date +%s); left=$(( target - now )); [[ $left -le 0 ]] && break
-    state_set resume_at "$(date -u -d "@$target" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo "$target")"
+    state_set resume_at "$(tf_date_from -u "@$target" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo "$target")"
     if [[ $left -gt 300 ]]; then nap 300; else nap "$left"; fi
   done
   state_set resume_at ""
@@ -405,16 +484,14 @@ run_cycle() { # runs "${CMD[@]}" in $APP_DIR, output to $OUT and $LOG; sets RC,
   STALLED=0
   local quiet=0 prev=-1 size
   if [[ -n "${TF_GOAL_FAKE_CMD:-}" ]]; then CMD=(bash -c "$TF_GOAL_FAKE_CMD"); fi
-  if command -v setsid >/dev/null 2>&1; then
-    ( cd "$APP_DIR" && TF_YOLO=1 exec setsid "${CMD[@]}" ) > >(tee -a "$LOG" > "$OUT") 2>&1 &
-  else
-    ( cd "$APP_DIR" && TF_YOLO=1 exec "${CMD[@]}" ) > >(tee -a "$LOG" > "$OUT") 2>&1 &
-  fi
+  # Its own session and process group (tf_setsid: setsid(1), or python3/perl on a Mac), so
+  # kill_child can stop the whole tree.
+  ( cd "$APP_DIR" && TF_YOLO=1 tf_setsid --exec "${CMD[@]}" ) > >(tee -a "$LOG" > "$OUT") 2>&1 &
   CHILD=$!
   while kill -0 "$CHILD" 2>/dev/null; do
     nap "$STALL_TICK"
     kill -0 "$CHILD" 2>/dev/null || break
-    size="$(stat -c %s "$OUT" 2>/dev/null || echo 0)"
+    size="$(tf_stat_size "$OUT" 2>/dev/null || echo 0)"
     if [[ "$size" == "$prev" ]]; then quiet=$(( quiet + STALL_TICK )); else quiet=0; prev="$size"; fi
     if [[ "$STALL_SEC" -gt 0 && $quiet -ge "$STALL_SEC" ]]; then
       log "STALL: no output for $(( quiet / 60 ))m$(( quiet % 60 ))s (cycle $CYCLE, ${size} bytes) — stopping the harness, re-prompting"
@@ -492,7 +569,7 @@ while :; do
   OUT="$STATE_DIR/goal-cycle-$CYCLE.out"
   if [[ $DRY -eq 1 ]]; then echo "dry run — would launch cycle $CYCLE ($KIND):" >&2; printf '  %q' "${CMD[@]}"; echo; exit 0; fi
   state_set cycle "$CYCLE"; CYCLE_START="$(date +%s)"
-  log "cycle $CYCLE ($KIND) → ${CMD[*]:0:6} … (prompt ${#CMD[-1]} chars)"
+  log "cycle $CYCLE ($KIND) → ${CMD[*]:0:6} … (prompt ${#CMD[${#CMD[@]}-1]} chars)"
 
   # The run's start is now, not when the agent reaches step 0: write an unclaimed marker the
   # first command's `tf-phase.sh start` claims (MISS-TechieFlow-20260905-20).
@@ -507,7 +584,14 @@ while :; do
     CLASS=IDLE; DETAIL="stalled ${STALL_MIN}m"; HOW=""
     PERR="$(opencode_log_error "$CYCLE_START")"
     if [[ -n "$PERR" ]] && grep -qiE "usage limit|monthly|balance|quota|rate limit|429|insufficient|billing|unauthorized|api key" <<<"$PERR"; then
-      log "the provider refused the model while the harness printed nothing (cycle $CYCLE): $PERR — the owner must act (enable balance, wait for the reset, or pick another model); stopping"
+      log "the provider refused the model while the harness printed nothing (cycle $CYCLE): $PERR"
+      # A monthly limit or an empty balance states no reset time, so the model is parked for the
+      # probe window and the run continues on the next model in the tier. Only when the chain is
+      # exhausted does this stay what it was before 2026-09-10: the owner's problem, exit 5.
+      if try_fallback "" "provider refused the model: ${PERR:0:120}"; then
+        STALLS=0; state_set stalls 0; BACKOFF=120; continue
+      fi
+      log "no other model in the $TIER chain is available — the owner must act (enable balance, wait for the reset, or pick another model); stopping"
       state_set last_reason "provider-limit" ended "$(ts)"
       exit 5
     fi
@@ -525,6 +609,9 @@ while :; do
   fi
   case "$CLASS" in
     LIMIT)
+      # Another model in the same tier beats waiting, when there is one.
+      if [[ "$HOW" == probe ]]; then _FB_UNTIL=""; else _FB_UNTIL="$DETAIL"; fi
+      if try_fallback "$_FB_UNTIL" "usage limit"; then BACKOFF=120; continue; fi
       if [[ "$HOW" == probe ]]; then
         log "USAGE LIMIT hit (cycle $CYCLE) but no reset time could be parsed from the message — probing every ${PROBE_MIN}m until the API answers again (max ${PROBE_MAX_H}h). Tail of the message:"
         tail -c 400 "$OUT" | tr '\n' ' ' | sed 's/^/    /' | tee -a "$LOG" >&2; echo >&2
@@ -533,7 +620,7 @@ while :; do
         log "probe succeeded — resuming session ${SESSION_ID:-(--continue)} after a ${BUFFER_MIN}m buffer"
         nap $(( BUFFER_MIN * 60 ))
       else
-        WHEN="$(date -d "@$DETAIL" '+%Y-%m-%d %H:%M %Z' 2>/dev/null || echo "$DETAIL")"
+        WHEN="$(tf_date_from "@$DETAIL" '+%Y-%m-%d %H:%M %Z' 2>/dev/null || echo "$DETAIL")"
         log "USAGE LIMIT hit (cycle $CYCLE) — RETRY AT $WHEN (stated reset + ${BUFFER_MIN}m buffer). Sleeping."
         state_set last_reason "limit" resume_at "$WHEN"
         sleep_until "$DETAIL"

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

@@ -48,13 +48,18 @@ _detect() {
   fi
   local k
   for k in $(compgen -v | grep '^OPENCODE' 2>/dev/null); do printf 'opencode'; return; done
-  # /proc ancestry walk (Linux/WSL); bounded
+  # ancestry walk, bounded: /proc on Linux/WSL, ps where there is no /proc (macOS)
   local pid=$PPID name ppid seen=0 stat
   while [[ -n "$pid" && "$pid" -gt 1 && $seen -lt 12 ]]; do
     seen=$((seen + 1))
-    stat="$(cat /proc/$pid/stat 2>/dev/null)" || break
-    name="${stat#*(}"; name="${name%%)*}"
-    ppid="$(printf '%s' "${stat##*) }" | awk '{print $2}')"
+    if [[ -d /proc/self ]]; then
+      stat="$(cat /proc/$pid/stat 2>/dev/null)" || break
+      name="${stat#*(}"; name="${name%%)*}"
+      ppid="$(printf '%s' "${stat##*) }" | awk '{print $2}')"
+    else
+      ppid="$(ps -o ppid= -p "$pid" 2>/dev/null | tr -d ' ')"; [[ -n "$ppid" ]] || break
+      name="$(ps -o comm= -p "$pid" 2>/dev/null)"; name="${name##*/}"
+    fi
     case "$name" in
       *opencode*) printf 'opencode'; return ;;
       *claude*)   printf 'claude-code'; return ;;

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

@@ -0,0 +1,29 @@
+# tf-lock.sh — one build or browser check at a time per repository. Sourced, not run.
+#   source "$HERE/tf-lock.sh"; tf_take_lock <label>     waits for the lock, then holds it until exit
+# A directory, because mkdir is atomic on every drive this runs on. A lock whose process has gone
+# is taken over. A script started by the holder (tf-verify-tests.sh running tf-build.sh) shares it
+# through TF_REPO_LOCK_PID. TF_BUILD_LOCK_MAX seconds to wait (1800). (TF-043, TfLens TF-048)
+TF_LOCK="tests/.artifacts/build/.lock"
+tf_release_lock() { [[ "$(cut -d' ' -f1 "$TF_LOCK/owner" 2>/dev/null)" == "$$" ]] && rm -rf "$TF_LOCK"; }
+tf_take_lock() {
+  local label="${1:-}" waited=0 max="${TF_BUILD_LOCK_MAX:-1800}" said=0 owner opid ohost
+  if [[ -n "${TF_REPO_LOCK_PID:-}" ]] && kill -0 "$TF_REPO_LOCK_PID" 2>/dev/null; then return 0; fi
+  mkdir -p "$(dirname "$TF_LOCK")"
+  while ! mkdir "$TF_LOCK" 2>/dev/null; do
+    owner="$(cat "$TF_LOCK/owner" 2>/dev/null)"; opid="$(cut -d' ' -f1 <<<"$owner")"; ohost="$(cut -d' ' -f2 <<<"$owner")"
+    if [[ -z "$owner" ]]; then
+      [[ -n "$(find "$TF_LOCK" -maxdepth 0 -mmin +1 2>/dev/null)" ]] && { rm -rf "$TF_LOCK"; continue; }
+    elif [[ "$ohost" == "$(hostname)" ]] && ! kill -0 "$opid" 2>/dev/null; then
+      rm -rf "$TF_LOCK"; continue
+    fi
+    [[ $said -eq 0 ]] && { echo "wait  another build or browser check is running in this repository (${owner:-starting}); this one starts when it finishes" >&2; said=1; }
+    if [[ $waited -ge $max ]]; then
+      echo "NOT-RUN another build or browser check held this repository for $((max / 60)) minutes ($owner). If nothing is running, remove $TF_LOCK and run again. Not a code error"
+      exit 2
+    fi
+    sleep 3; waited=$((waited + 3))
+  done
+  echo "$$ $(hostname) $label $(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$TF_LOCK/owner"
+  export TF_REPO_LOCK_PID=$$
+  trap tf_release_lock EXIT
+}