@appchy/jarvis 0.1.37 → 0.1.39

package/harness/harness/shift.py

@@ -0,0 +1,348 @@
+"""A shift: one instance, one task, no collisions.
+
+`move <name> in-progress` requires already knowing the name, and nothing computed
+it — so a scheduled instance had no entry point, and the first thing it would have
+had to do is read the whole board and choose, which is a judgement call made before
+any of the harness's guard rails are loaded. `next` is that entry point, and every
+input it uses already existed: priority, `depends_on`, the bucket, the version's
+derived status, and the task's `tier:` against `autonomy.ceiling`.
+
+**Coordination is a file, not a service.** A `.claim` beside `task.md` holds the
+instance id and an expiry. A second `next` never returns a claimed task; a claim
+whose `code:` regions are already held live by another instance is refused and the
+selector moves on, which reuses the region overlap `jarvis work code` has computed all
+along. Expired claims are reaped on read, so an instance that crashes at 3am frees
+its work without anyone being paged.
+
+`status` is the same data read from the other end — what shipped, what is waiting
+on you, what is at risk. Derived, never declared.
+"""
+import json
+import shutil
+import sys
+from datetime import date, datetime, timedelta, timezone
+from pathlib import Path
+
+from .tree import BLOCKED, BUCKETS, die, find_work_root, rel
+from .frontmatter import rewrite_file
+from .model import locate, record_session, scan
+from .generate import _sync
+from . import autonomy, events, peers
+# The ceiling is read through the MODULE, never bound in with `from … import`.
+# A `from .autonomy import CEILING` captures the value at import time, so
+# `config.apply` setting it afterwards would leave this file quietly running on
+# the shipped default — one fact with two owners, which is the drift the whole
+# harness is built to avoid.
+from .autonomy import _open_questions, tier_of
+
+CLAIM = ".claim"
+#: How long a claim is good for. Long enough that a real task finishes inside it,
+#: short enough that a crashed instance's work is takeable the same day. Config
+#: moves it (`autonomy.lease_minutes`).
+LEASE_MINUTES = 240
+
+
+def _now():
+    return datetime.now(timezone.utc).replace(microsecond=0)
+
+
+def read_claim(folder: Path):
+    """The live claim on a task folder, or None. An expired or unreadable claim is
+    treated as absent — a lease nobody can parse must not be able to strand work
+    forever, which is the failure mode of every lock that fails closed."""
+    p = folder / CLAIM
+    if not p.is_file():
+        return None
+    try:
+        data = json.loads(p.read_text())
+        expires = datetime.fromisoformat(str(data["expires"]))
+    except (OSError, ValueError, KeyError, json.JSONDecodeError):
+        return None
+    if expires <= _now():
+        return None
+    return data
+
+
+def _write_claim(folder: Path, instance: str) -> dict:
+    data = {
+        "instance": instance,
+        # WHICH BOX, recorded because an id alone cannot say whether the session
+        # holding this is one you can talk to or one on another machine entirely.
+        # A claim never enters git, so this is the only place the pairing exists.
+        "machine": peers.here(),
+        "taken": _now().isoformat(),
+        "expires": (_now() + timedelta(minutes=LEASE_MINUTES)).isoformat(),
+    }
+    (folder / CLAIM).write_text(json.dumps(data, indent=2) + "\n")
+    return data
+
+
+def _live_claims(s: dict) -> list:
+    """Every unexpired claim across the tree, as (claim, task) — the input to both
+    the same-task check and the region-conflict check."""
+    out = []
+    for v in s["versions"]:
+        for t in v.all_tasks():
+            c = read_claim(t.folder)
+            if c:
+                out.append((c, t))
+    return out
+
+
+def _blockers(task, s: dict) -> str:
+    """Why an unattended run may NOT take this task, or "" if it may. One string,
+    because `next` prints it when nothing is eligible — a cron log that says
+    "nothing to do" and not why is a log nobody can debug."""
+    done = {t.name for v in s["versions"] for t in v.all_tasks()
+            if t.status == "complete"}
+    missing = [d for d in task.depends_on if d not in done]
+    if missing:
+        return f"depends on incomplete: {', '.join(missing)}"
+    tier = tier_of(task)
+    if tier > autonomy.CEILING:
+        return (f"tier {tier} > autonomy.ceiling {autonomy.CEILING} — this one is yours to "
+                f"decide, not the shift's")
+    return ""
+
+
+def _region_conflict(task, claims: list) -> str:
+    if not task.code:
+        return ""
+    for c, other in claims:
+        if other.name == task.name:
+            continue
+        overlap = sorted(set(task.code) & set(other.code))
+        if overlap:
+            # Naming the holder is only half an answer — the half that leaves you
+            # waiting for a lease. The other half is whether that session is one
+            # you can actually talk to about it.
+            return (f"code region(s) {', '.join(overlap)} held by "
+                    f"'{other.name}' · {peers.of_claim(c)}")
+    return ""
+
+
+def cmd_next(args) -> int:
+    """Hand this instance exactly one task, and claim it.
+
+    `--peek` selects without claiming or moving — for a human asking what the shift
+    would take next, which must not have the side effect of taking it."""
+    root = find_work_root()
+    instance = (args.get("instance") or events.instance_id() or "local").strip()
+    peek = bool(args.get("peek"))
+    s = scan(root)
+    claims = _live_claims(s)
+
+    # An instance that already holds work resumes it rather than taking more. One
+    # instance, one task — a shift juggling three tasks is three half-finished
+    # tasks, and unattended nobody notices until morning.
+    for c, t in claims:
+        if c["instance"] == instance:
+            print(f"RESUME  {t.name} — {t.title}   [claimed {c['taken']}]")
+            _read_order(t, root)
+            return 0
+
+    live = [v for v in s["versions"] if not v.released]
+    candidates, skipped = [], []
+    for v in sorted(live, key=lambda x: (x.order, x.name)):
+        for t in v.bucket("queue"):
+            if read_claim(t.folder):
+                skipped.append((t, "claimed by another instance"))
+                continue
+            why = _blockers(t, s) or _region_conflict(t, claims)
+            if why:
+                skipped.append((t, why))
+                continue
+            candidates.append((t.priority_rank(), v.order, t.name, t))
+
+    if not candidates:
+        blocked = [t for v in live for t in v.bucket(BLOCKED)]
+        print("nothing to take.")
+        if blocked:
+            print(f"  {len(blocked)} task(s) waiting on a human — `jarvis work needs`")
+        for t, why in sorted(skipped, key=lambda r: r[0].name)[:10]:
+            print(f"  skipped {t.name}: {why}")
+        if not blocked and not skipped:
+            print("  the queue is empty — nothing is cut and ready.")
+        return 0
+
+    candidates.sort(key=lambda r: (r[0], r[1], r[2]))
+    task = candidates[0][3]
+
+    if peek:
+        print(f"NEXT (peek)  {task.name} — {task.title}   "
+              f"[{task.priority} · tier {tier_of(task)}]")
+        return 0
+
+    container = task.folder.parent.parent
+    dest = container / "in-progress" / task.name
+    if dest.exists():
+        die(f"{rel(dest, root)} already exists")
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    shutil.move(str(task.folder), str(dest))
+    md = dest / "task.md"
+    rewrite_file(
+        md,
+        lambda d: d.update({"updated": date.today().isoformat()}),
+    )
+    claim = _write_claim(dest, instance)
+    record_session(dest)
+    events.append(root, "moved", task.name, **{"from": "queue", "to": "in-progress"})
+    events.append(root, "claimed", task.name, expires=claim["expires"])
+
+    print(f"TAKE  {task.name} — {task.title}   "
+          f"[{task.priority} · tier {tier_of(task)} · lease to {claim['expires']}]")
+    task = locate(root, task.name)
+    _read_order(task, root)
+    _sync(root)
+    return 0
+
+
+def _read_order(task, root) -> None:
+    """The cold-start spine, in the order `references/operations.md` prescribes.
+    Printed rather than assumed: an unattended session has no prior conversation,
+    so the one thing it must not have to infer is what to read."""
+    print("\n  read, in this order:")
+    print(f"    1. {rel(task.folder / 'task.md', root)}   the brief")
+    for f, what in (("handoff.md", "where things stand"),
+                    ("plan.md", "design + as-found + build"),
+                    ("research.md", "raw findings")):
+        if (task.folder / f).is_file():
+            print(f"       {rel(task.folder / f, root)}   {what}")
+    print(f"    2. jarvis work rules --task {task.name}   what constrains it")
+    if task.epic:
+        print(f"    3. the parent epic.md §Plan   the design every sibling builds against")
+    print(f"    4. jarvis work verify   before you claim it is done\n")
+    print(f"  tier {tier_of(task)} · ceiling {autonomy.CEILING} — "
+          + ("decide inside the plan; park product/UX calls with `jarvis work ask`."
+             if tier_of(task) <= autonomy.CEILING else
+             "ABOVE CEILING: do not decide alone."))
+
+
+def cmd_drop(args) -> int:
+    """Give a task back — the honest end to a shift that cannot finish it."""
+    root = find_work_root()
+    task = locate(root, args["name"])
+    if not task:
+        die(f"no task named '{args['name']}' found")
+    p = task.folder / CLAIM
+    if p.is_file():
+        p.unlink()
+        events.append(root, "released-claim", task.name,
+                      why=(args.get("why") or "").strip() or None)
+        print(f"released claim on '{task.name}'")
+    else:
+        print(f"'{task.name}' has no claim")
+    return 0
+
+
+def _ago(ts: str) -> str:
+    """How long ago a recorded moment was, in the coarsest unit that still says
+    something. "6h ago" answers *is anyone on this* far better than a timestamp the
+    reader has to subtract from now, and the difference between 6 and 7 hours never
+    changes what they do about it."""
+    try:
+        when = datetime.fromisoformat(ts.replace("Z", "+00:00"))
+    except (TypeError, ValueError, AttributeError):
+        return "at an unrecorded time"
+    if when.tzinfo is None:
+        when = when.replace(tzinfo=timezone.utc)
+    mins = int((datetime.now(timezone.utc) - when).total_seconds() // 60)
+    if mins < 1:
+        return "just now"
+    if mins < 60:
+        return f"{mins}m ago"
+    if mins < 60 * 48:
+        return f"{mins // 60}h ago"
+    return f"{mins // (60 * 24)}d ago"
+
+
+def cmd_status(args) -> int:
+    """The founder's morning read, in the order the questions actually get asked.
+
+    Every line is derived — from the tree for what is true now, from the log for
+    what happened. Nothing here is a field somebody wrote saying how it is going."""
+    root = find_work_root()
+    from .report import _say_staleness
+
+    _say_staleness(root)
+    s = scan(root)
+    live = [v for v in s["versions"] if not v.released]
+
+    waiting = [(t, q) for v in s["versions"] for t in v.all_tasks()
+               for q in _open_questions(t)]
+    print(f"WAITING ON YOU  ({len(waiting)})")
+    for t, q in waiting[:8]:
+        parts = q.split("  ")
+        print(f"  {t.name}: {'  '.join(parts[2:]) if len(parts) > 2 else q}")
+    if not waiting:
+        print("  nothing — the shift is not blocked on you.")
+
+    # One read of the record, shared by every section below. It is a `git log`
+    # under the git backend, so asking three times is three subprocesses for one
+    # answer that cannot change between them.
+    log = events.read(root)
+    recent = [e for e in log if e["event"] == "completed"][-5:]
+    print(f"\nSHIPPED  (last {len(recent)})")
+    for e in recent:
+        print(f"  {e['ts'][:10]}  {e['name']}"
+              + (f" — {e['delivered']}" if e.get("delivered") else ""))
+    if not recent:
+        print("  nothing recorded yet.")
+
+    # Who last touched each item, out of the commits. A lease answers this only for
+    # the unattended loop — an interactive session writes none at all, so reading
+    # claims alone printed `unclaimed` against every item a person was working and
+    # told the one screen the shift is read from nothing whatsoever.
+    touched = {}
+    for e in log:
+        if e.get("by"):
+            touched[e["name"]] = e
+
+    in_flight = [t for v in live for t in v.bucket("in-progress")]
+    print(f"\nIN FLIGHT  ({len(in_flight)})")
+    for t in in_flight:
+        c = read_claim(t.folder)
+        last = touched.get(t.name)
+        if c:
+            who = f" · {c['instance'][:8]} until {c['expires'][11:16]}Z"
+        elif last:
+            who = f" · last touched {_ago(last['ts'])}"
+        else:
+            who = " · never touched"
+        print(f"  {t.name} — {t.title}  [tier {tier_of(t)}{who}]")
+        # Only for work that is somebody ELSE's: on your own tasks this would be a
+        # line about yourself on every status, which is how a useful line becomes
+        # one people stop reading.
+        if c and c.get("instance") != peers.me():
+            print(f"      {peers.of_claim(c)}")
+        elif not c and last and last["by"] != peers.me():
+            print(f"      {peers.describe(last['by'], last.get('machine', ''))}")
+    if not in_flight:
+        print("  nothing is being worked on.")
+
+    # At risk: claimed-but-expired (an instance died), and gates that keep refusing.
+    stale = [t for t in in_flight if not read_claim(t.folder) and (t.folder / CLAIM).is_file()]
+    # A task refused repeatedly is a task not converging — UNLESS it is parked with
+    # an open question, which is the designed outcome rather than a failure. Counting
+    # those would put the harness's own correct behaviour on the risk list, and a
+    # risk list with routine entries on it is one that stops being read.
+    waiting = {t.name for v in live for t in v.bucket(BLOCKED)}
+    refused = {}
+    for e in log:
+        if e["event"] == "gate-refused" and e["name"] not in waiting:
+            refused[e["name"]] = refused.get(e["name"], 0) + 1
+    repeat = {n: c for n, c in refused.items() if c >= 2}
+    print(f"\nAT RISK  ({len(stale) + len(repeat)})")
+    for t in stale:
+        print(f"  {t.name}: lease expired — the instance working it is gone")
+    for n, c in sorted(repeat.items()):
+        print(f"  {n}: completion refused {c}× — it is not converging")
+    if not stale and not repeat:
+        print("  nothing.")
+
+    print("\nBOARD")
+    for v in sorted(s["versions"], key=lambda x: (x.order, x.name)):
+        counts = " · ".join(f"{b} {len(v.bucket(b))}" for b in BUCKETS
+                            if v.bucket(b))
+        print(f"  {v.name} [{v.status()}]  {counts or 'empty'}")
+    return 0