@appchy/jarvis 0.1.122 → 0.1.124

package/harness/harness/config.py

@@ -868,6 +868,27 @@ def _what_this_repo_has_decided(cfg: dict, repo) -> list:
             out.append("what the releases are for, so a plan does not win this week "
                        "and cost the next one:\n      " + "\n      ".join(cuts))
     return out
+def _who_else_is_here(repo) -> str:
+    """The peers line, or `""` — composed by `peers`, which is the one place that
+    knows what a peer is, and assembled here only because this is where the board's
+    own history is already being read.
+
+    Everything it needs is best-effort: a repo that is not a git checkout has no
+    history and no branch, and the line degrades to who is live rather than failing.
+    A session start that cannot be told about its peers must still be told everything
+    else.
+    """
+    if repo is None:
+        return ""
+    from . import events, git, peers
+    root = Path(repo) / "work"
+    try:
+        rows = events.read(root) if root.is_dir() else []
+    except (OSError, ValueError):
+        rows = []
+    return peers.briefing(repo, rows, git.branch(repo))
+
+
 #: What the block is, said once, above every line of it. It names no repo and makes
 #: no claim a config could contradict — which is what lets it be the same sentence
 #: wherever the block is served.
@@ -893,6 +914,15 @@ def session_pointers(cfg: dict, repo=None) -> list:
     out = [f"the board: tasks live under `work/` — `{cli()} list` shows what is "
            f"moving, `{cli()} where <id>` resolves any rule id to its home."]
 
+    # Said FIRST of everything derived, and only when there is somebody: a session
+    # that picks up overlapping work finds out by overwriting it, and the moment to
+    # prevent that is before it has read anything else. Silence when alone is the
+    # design — this reaches every session in every repo running the harness, forever,
+    # so it has to cost nothing on the ordinary day.
+    peers_here = _who_else_is_here(repo)
+    if peers_here:
+        out.append(peers_here)
+
     # The guidance stack, ANNOUNCED. What ships is an engine plus somebody's
     # methodology, and a session that cannot tell which is which will cite the
     # preset's reasoning as though the tool enforced it. Saying it also makes an

package/harness/harness/git.py

@@ -199,6 +199,15 @@ def machine() -> str:
     return (os.environ.get("WORK_MACHINE") or socket.gethostname() or "").strip()
 
 
+def branch(repo) -> str:
+    """Which branch this checkout is on, or `""` — a detached HEAD and a directory
+    that is not a repo at all both answer the same way, because neither has a branch
+    to name and a caller only ever wants the name."""
+    code, out, _ = _git(repo, "rev-parse", "--abbrev-ref", "HEAD", timeout=5)
+    named = out.strip()
+    return "" if code != 0 or named == "HEAD" else named
+
+
 def _git(repo, *argv, timeout=30):
     """Run one git command. Returns (code, stdout, stderr); a git that is missing or
     hangs is a non-zero code with a reason, never an exception — a board write must

package/harness/harness/kickoff.py

@@ -167,15 +167,25 @@ def session_name(task) -> str:
     one Claude Code derives a name from the FOLDER — identical for every session
     in a repo, so several runs are told apart only by an id nobody reads.
 
+    **It is the item's NAME, not its title** (founder, 2026-09-12). A title is a
+    sentence — "The verify lock refuses cleanly but cannot say you are queued, or
+    that you were displaced" is 90 characters — and a picker truncates it to the
+    half that carries no information, so four sessions read as four rows of
+    near-identical prose. Worse, it is not a string a person can type: this name
+    is also what `ListAgents` lists and `SendMessage` addresses, so it has to be
+    something somebody can say out loud to point an agent at one session. The
+    item's name is already that — short, unique across the whole board by
+    construction, and the same word the person would use for the work itself.
+
     A run is numbered by how many have already worked the item, so the first is
-    just the title and the fifth says it is the fifth. The number leads because
+    just the name and the fifth says it is the fifth. The number leads because
     that is the column a picker never truncates, and the count comes off
     `sessions:` rather than being carried in the prompt: the wrap has just
     recorded the run doing the wrapping, so the successor is the next one along
     and nothing has to remember what number it is.
     """
     ordinal = len(task.sessions) + 1
-    return task.title if ordinal == 1 else f"{ordinal} · {task.title}"
+    return task.name if ordinal == 1 else f"{ordinal} · {task.name}"
 
 
 def cmd_kickoff(args) -> int:

package/harness/harness/peers.cases.json

@@ -0,0 +1,141 @@
+{
+  "why": [
+    "One directory is read by two languages: the harness reads ~/.claude/sessions itself, and",
+    "the board's TypeScript reads it again rather than paying a subprocess on every board list.",
+    "Two readers of one directory is where one session comes to be described two ways, so both",
+    "run THESE cases and assert THIS answer. A drift between them is a red test in both suites",
+    "rather than two answers a person has to reconcile.",
+    "",
+    "A case's `sessions` is null when the directory does not exist at all, which is a different",
+    "answer from an empty directory and must stay different: no directory means this client does",
+    "not say, and that is where every agent publishing nothing sits.",
+    "",
+    "`pid` is a marker, never a number: `self` is the running test's own process, which is the",
+    "only pid a test can be sure is alive, and `dead` is one nothing can be occupying."
+  ],
+  "cases": [
+    {
+      "name": "a run with one live process is reachable by the name it published",
+      "sessions": [
+        { "file": "1.json", "sessionId": "alive-2222", "name": "repo-a8", "pid": "self", "entrypoint": "cli" }
+      ],
+      "ask": "alive-2222",
+      "expect": {
+        "live": "running",
+        "processes": 1,
+        "addresses": [{ "name": "repo-a8", "from": "a terminal" }]
+      }
+    },
+    {
+      "name": "a run whose process is gone is ended, not merely unlisted",
+      "sessions": [
+        { "file": "1.json", "sessionId": "alive-2222", "name": "repo-a8", "pid": "self", "entrypoint": "cli" },
+        { "file": "2.json", "sessionId": "ghost-3333", "name": "repo-b7", "pid": "dead", "entrypoint": "cli" }
+      ],
+      "ask": "ghost-3333",
+      "expect": { "live": "ended", "processes": 0, "addresses": [] }
+    },
+    {
+      "name": "a run nothing published is ended, because something published a list without it",
+      "sessions": [
+        { "file": "1.json", "sessionId": "alive-2222", "name": "repo-a8", "pid": "self", "entrypoint": "cli" }
+      ],
+      "ask": "never-heard-of-it",
+      "expect": { "live": "ended", "processes": 0, "addresses": [] }
+    },
+    {
+      "name": "a take that named no run at all concludes nothing, because there is nothing to look up",
+      "sessions": [
+        { "file": "1.json", "sessionId": "alive-2222", "name": "repo-a8", "pid": "self", "entrypoint": "cli" }
+      ],
+      "ask": "",
+      "expect": { "live": "unknown", "processes": 0, "addresses": [] }
+    },
+    {
+      "name": "a client that publishes no list makes every run unknown, never ended",
+      "sessions": null,
+      "ask": "alive-2222",
+      "expect": { "live": "unknown", "processes": 0, "addresses": [] }
+    },
+    {
+      "name": "an empty list is a claim, so a run not on it has ended",
+      "sessions": [],
+      "ask": "alive-2222",
+      "expect": { "live": "ended", "processes": 0, "addresses": [] }
+    },
+    {
+      "name": "two live processes on one id are a fork, named both ways and neither picked",
+      "sessions": [
+        { "file": "20558.json", "sessionId": "forked-4444", "name": "jarvis-9a", "pid": "self", "entrypoint": "claude-vscode" },
+        { "file": "15750.json", "sessionId": "forked-4444", "name": "the harness stops", "pid": "self", "entrypoint": "cli" }
+      ],
+      "ask": "forked-4444",
+      "expect": {
+        "live": "forked",
+        "processes": 2,
+        "addresses": [
+          { "name": "jarvis-9a", "from": "an editor" },
+          { "name": "the harness stops", "from": "a terminal" }
+        ]
+      }
+    },
+    {
+      "name": "a fork is counted by its processes even when one of them published no name",
+      "sessions": [
+        { "file": "1.json", "sessionId": "forked-5555", "name": "named-one", "pid": "self", "entrypoint": "cli" },
+        { "file": "2.json", "sessionId": "forked-5555", "name": "", "pid": "self", "entrypoint": "claude-vscode" }
+      ],
+      "ask": "forked-5555",
+      "expect": {
+        "live": "forked",
+        "processes": 2,
+        "addresses": [{ "name": "named-one", "from": "a terminal" }]
+      }
+    },
+    {
+      "name": "a live run that published no name is running, with nothing to address it by",
+      "sessions": [
+        { "file": "1.json", "sessionId": "nameless-6666", "name": "", "pid": "self", "entrypoint": "cli" }
+      ],
+      "ask": "nameless-6666",
+      "expect": { "live": "running", "processes": 1, "addresses": [] }
+    },
+    {
+      "name": "a door this does not know is passed through under the name its client gave it",
+      "sessions": [
+        { "file": "1.json", "sessionId": "alive-7777", "name": "repo-c1", "pid": "self", "entrypoint": "some-future-client" }
+      ],
+      "ask": "alive-7777",
+      "expect": {
+        "live": "running",
+        "processes": 1,
+        "addresses": [{ "name": "repo-c1", "from": "some-future-client" }]
+      }
+    },
+    {
+      "name": "a run that names no door at all is still reachable by name",
+      "sessions": [
+        { "file": "1.json", "sessionId": "alive-8888", "name": "repo-d2", "pid": "self" }
+      ],
+      "ask": "alive-8888",
+      "expect": {
+        "live": "running",
+        "processes": 1,
+        "addresses": [{ "name": "repo-d2", "from": "" }]
+      }
+    },
+    {
+      "name": "a half-written file is skipped rather than read as a dead session",
+      "sessions": [
+        { "file": "1.json", "sessionId": "alive-9999", "name": "repo-e3", "pid": "self", "entrypoint": "cli" },
+        { "file": "2.json", "raw": "{\"sessionId\": \"tru" }
+      ],
+      "ask": "alive-9999",
+      "expect": {
+        "live": "running",
+        "processes": 1,
+        "addresses": [{ "name": "repo-e3", "from": "a terminal" }]
+      }
+    }
+  ]
+}

package/harness/harness/peers.py

@@ -29,6 +29,7 @@ import os
 from pathlib import Path
 
 from . import git
+from .tree import cli
 
 #: How much of an instance id is worth showing. Eight hex characters is what every
 #: surface here has always printed and what `ListAgents` matches on sight.
@@ -84,6 +85,12 @@ def alive(pid) -> bool:
 SESSIONS = "WORK_SESSIONS_DIR"
 DEFAULT_SESSIONS = "~/.claude/sessions"
 
+#: What a client calls the door a run came through, in words a person reads. A door
+#: this does not know is passed through under the client's own name, because a name
+#: we have not met still beats a guess — and there must be nothing here a client is
+#: REQUIRED to publish for the rest of the answer to hold.
+DOORS = {"cli": "a terminal", "claude-vscode": "an editor"}
+
 #: Answers already worked out this run, keyed by the directory they came from. Keyed
 #: rather than a single slot because the tests point this at several directories in
 #: one process, and a cache that ignored where it read from would answer for the
@@ -95,6 +102,14 @@ def _live():
     """Every agent session live on THIS machine, keyed by session id, as the client
     published it — or `None` when nothing here publishes that at all.
 
+    The value is a LIST because one session id can be more than one live process.
+    Opening a running session in a second local client starts a second process on the
+    same id rather than attaching to the first, so both are alive and both append to
+    one transcript. Keying one entry per id silently dropped whichever file sorted
+    earlier, which made the name handed to a reader depend on how two pids happened to
+    sort — measured on this machine, five of seventeen live ids are doubled, and which
+    half won flipped from pair to pair.
+
     The whole entry rather than one field of it, because two questions are asked of
     this directory now: who is running, and who is running IN THIS CHECKOUT. They
     want the same scan, the same pid check and the same cache, and reading the
@@ -139,22 +154,44 @@ def _live():
         run = str(entry.get("sessionId", ""))
         if not run or not alive(entry.get("pid")):
             continue
-        out[run] = entry
+        out.setdefault(run, []).append(entry)
     _RUNNING[key] = out
     return out
 
 
+def addresses(entries) -> list:
+    """What reaches each of a session's live processes: `(name, door)` pairs, sorted.
+
+    A process that publishes no name is left out rather than listed blank — naming it
+    would send a reader looking for something `SendMessage` will not take.
+    """
+    out = []
+    for entry in entries:
+        name = str(entry.get("name", "")).strip()
+        if not name:
+            continue
+        door = str(entry.get("entrypoint", "")).strip()
+        out.append((name, DOORS.get(door, door)))
+    out.sort()
+    return out
+
+
 def running():
-    """Every agent session live on THIS machine as `{session id: name}`.
+    """Every agent session live on THIS machine as `{session id: [name, ...]}`.
 
     `None` and `{}` stay as far apart here as they are in `_live`: no directory
     means *this client does not say*, and an empty mapping means something
     published a list this session was not on.
+
+    The names are a LIST for the same reason `_live` holds one: an id answering to two
+    names is a session running as two processes, and picking one of them is the defect
+    this shape exists to make impossible.
     """
     live = _live()
     if live is None:
         return None
-    return {run: str(entry.get("name", "")).strip() for run, entry in live.items()}
+    return {run: [name for name, _ in addresses(entries)]
+            for run, entries in live.items()}
 
 
 def _inside(where: str, root) -> bool:
@@ -195,24 +232,65 @@ def sharing(root) -> str:
     if not live:
         return ""
     mine = me()
-    names = []
-    for run, entry in live.items():
-        if run == mine or not _inside(str(entry.get("cwd", "")), root):
+    names, runs = [], 0
+    for run, entries in live.items():
+        if run == mine:
             continue
-        name = str(entry.get("name", "")).strip()
-        # A session with no published name cannot be addressed, so naming it would
-        # send a reader looking for something `SendMessage` will not take.
-        if name:
-            names.append(name)
+        found = addresses([e for e in entries
+                           if _inside(str(e.get("cwd", "")), root)])
+        if not found:
+            continue
+        runs += 1
+        names.extend(name for name, _ in found)
     names.sort()
     if not names:
         return ""
     shown = ", ".join(f"`{n}`" for n in names)
-    one = len(names) == 1
-    return (f"{len(names)} other session{'' if one else 's'} "
+    one = runs == 1
+    line = (f"{runs} other session{'' if one else 's'} "
             f"{'is' if one else 'are'} live in this checkout — {shown}. "
             f"`SendMessage` reaches {'it' if one else 'them'}; ask before you stash "
             f"or commit anything you did not write.")
+    # More names than sessions means one of them is running as two processes, which
+    # is a thing a reader about to message somebody needs to know: either name
+    # arrives at the same conversation, so picking between them decides nothing.
+    if len(names) > runs:
+        line += (" More names than sessions: one of these is running as two "
+                 "processes sharing a transcript, so either of its names reaches it.")
+    return line
+
+
+def reach(instance: str, host: str = "") -> dict:
+    """Whether a run is live and what reaches it — `{"live": …, "addresses": […]}`.
+
+    The structured answer, which `describe` renders into a sentence and the board's
+    TypeScript computes for itself. Both are pinned to one set of cases, because two
+    readers of one directory in two languages is exactly where the same session comes
+    to be described two ways, and a drift between them should be a red test rather
+    than two answers a person has to reconcile.
+
+    Four states, and the difference between two of them is the whole point. `ended`
+    is a CLAIM — something published a list and this run was not on it. `unknown` is
+    the absence of a claim: nothing here publishes one, or the run is on a machine
+    this one cannot see into. Collapsing them reports every peer of every client that
+    publishes nothing as dead, which is worse than the silence it replaces.
+    """
+    who = (instance or "").strip()
+    away = bool(host.strip()) and bool(here()) and host.strip() != here()
+    live = None if away else _live()
+    # A take that named no run at all is not a run that has ended — there is nothing to
+    # look up, so there is nothing to conclude. Reading the miss as `ended` would have
+    # every board write made without a session id report as abandoned work.
+    if live is None or not who:
+        return {"live": "unknown", "processes": 0, "addresses": []}
+    entries = live.get(who)
+    if not entries:
+        return {"live": "ended", "processes": 0, "addresses": []}
+    # Counted from the processes, never from the addresses: one of them publishing no
+    # name would otherwise make a fork report as though it were a single run.
+    return {"live": "forked" if len(entries) > 1 else "running",
+            "processes": len(entries),
+            "addresses": [{"name": n, "from": d} for n, d in addresses(entries)]}
 
 
 def describe(instance: str, host: str = "") -> str:
@@ -239,19 +317,28 @@ def describe(instance: str, host: str = "") -> str:
     if box and here() and box != here():
         return (f"{short} on {box} — another machine, so it cannot be reached from "
                 f"here; the board is the only thing you share")
-    live = running()
-    if live is None:
+    got = reach(who)
+    found = got["addresses"]
+    if got["live"] == "unknown":
         return (f"{short} — this machine: `ListAgents` lists it, `SendMessage` reaches "
                 f"it if the plan needs to change")
-    if who not in live:
+    if got["live"] == "ended":
         return (f"{short} — this machine, but that session has ENDED: there is "
                 f"nobody to reach, so this is abandoned rather than held")
-    name = live[who]
-    if not name:
+    if got["live"] == "forked":
+        if not found:
+            return (f"{short} — this machine, running as more than one process on ONE "
+                    f"session, none of which publishes a name to address it by")
+        shown = ", ".join(f"`{a['name']}`" + (f" ({a['from']})" if a["from"] else "")
+                          for a in found)
+        return (f"{short} — this machine, running as {got['processes']} processes on "
+                f"ONE session: {shown}. They share a transcript, so either reaches it "
+                f"and neither is THE address")
+    if not found:
         return (f"{short} — this machine and still running, though it publishes no "
                 f"name to address it by")
-    return (f"`{name}` ({short}) — this machine and still running: `SendMessage` "
-            f"reaches it if the plan needs to change")
+    return (f"`{found[0]['name']}` ({short}) — this machine and still running: "
+            f"`SendMessage` reaches it if the plan needs to change")
 
 
 def of_claim(claim: dict) -> str:
@@ -260,6 +347,88 @@ def of_claim(claim: dict) -> str:
     return describe(str(claim.get("instance", "")), str(claim.get("machine", "")))
 
 
+def briefing(root, rows: list, branch: str = "") -> str:
+    """Who else is working this checkout right now and what they are on, or `""`.
+
+    The line a session is handed before it does anything, and the answer a session
+    gets when it asks again. Silence when you are alone is the design rather than an
+    optimisation: every session in every repo running this harness reads this forever,
+    so it costs nothing on the ordinary day and earns its place on the day it matters.
+
+    `rows` is the board's own history, so what a peer holds comes from the commits
+    that took it rather than from a second store. It is passed in because the caller
+    already has it, and because reading it here would make this module import the one
+    that imports it.
+
+    Machine and branch are answered by construction and are not looked up per peer: a
+    session live in THIS checkout is on this machine and on whatever branch the
+    checkout is on. Saying so once is the whole of that answer.
+    """
+    live = _live()
+    if not live:
+        return ""
+    mine = me()
+    # The last board write each session made, which is the item it is on. A later
+    # write by somebody else does not move it: two sessions can hold one item.
+    held = {}
+    for row in rows:
+        by, name = str(row.get("by", "")), str(row.get("name", ""))
+        if by and name:
+            held[by] = name
+    said = []
+    for run in sorted(live):
+        if run == mine:
+            continue
+        found = addresses([e for e in live[run]
+                           if _inside(str(e.get("cwd", "")), root)])
+        if not found:
+            continue
+        shown = ", ".join(f"`{n}`" + (f" ({d})" if d else "") for n, d in found)
+        on = held.get(run)
+        note = " — TWO processes on one session, sharing a transcript" \
+            if len(found) > 1 else ""
+        said.append(f"{shown} · {'on ' + on if on else 'holding nothing on the board'}"
+                    f"{note}")
+    if not said:
+        return ""
+    where = f" on branch {branch}" if branch else ""
+    return (f"somebody else is working this checkout{where}, on this machine: "
+            + " · ".join(said)
+            + f". `SendMessage` reaches them by name. This is true as it prints and "
+              f"not for long — `{cli()} peers` asks again. Before you take work that "
+              f"overlaps theirs, ask them.")
+
+
+def cmd_peers(args=None) -> int:
+    """Ask again who else is here. The session block says it once at startup; this is
+    the same answer, now.
+
+    It ALWAYS prints, where the startup line says nothing when you are alone — a hook
+    that stays quiet costs a session nothing, while a command that answers with an
+    empty screen reads as broken rather than as an answer.
+    """
+    from . import events, git
+    from .tree import find_work_root
+    root = find_work_root()
+    repo = root.parent
+    try:
+        rows = events.read(root)
+    except (OSError, ValueError):
+        rows = []
+    said = briefing(repo, rows, git.branch(repo))
+    if said:
+        print(said)
+        return 0
+    live = _live()
+    # The two silences are different answers and only one of them is good news.
+    if live is None:
+        print("nothing on this machine publishes a session list, so who else is here "
+              "cannot be told from here — not that nobody is.")
+    else:
+        print("nobody else is working this checkout.")
+    return 0
+
+
 def arrivals(rows: list) -> str:
     """What just landed on the board from somewhere else, as one line.
 

package/harness/presets/appchy/PRESET.md

@@ -51,6 +51,11 @@ repo here has ONE server named `jarvis` and it is that repo's own — a checked-
 
 **The loop, in order:**
 
+0. **Who else is here.** The session block names them at startup and says nothing when you are
+   alone; `jarvis work peers` asks again, and it is the one answer in this loop that is stale the
+   moment it prints. Do it before you scope, because the cheapest collision to avoid is the one
+   where two sessions plan the same edit set — see §Somebody else is on it for what to do when the
+   answer is *somebody, on your regions*.
 1. **`map_brief {}`** — orient. What is in flight, the most-cited rules, health, and **whether the
    index is fresh**.
 2. **`map_scope {task}`** — the task in words → the edit set, the governing rules, the covering tests
@@ -503,15 +508,46 @@ them**:
 
 | You see it | When |
 |---|---|
+| the session block, at startup | somebody else is live in this checkout — who, on what, and how to reach them. **Silence means you are alone** |
+| `jarvis work peers` | you asked again, because that line was true when it printed and not for long |
 | `next` skips a task | its `code:` regions are held by another session |
 | `move <name> in-progress` | a live claim on it belongs to somebody else — a **note**, not a refusal |
 | `status` → IN FLIGHT | a task is held by a session that is not you |
+| a board read | every holder carries whether its run is still going and what reaches it |
 | any write | a pull brought board changes in: *the board moved under you — <what> · from <who>* |
 
 - **`— this machine`** → that session is addressable. `ListAgents` lists it, `SendMessage` reaches it.
   Use it when the plan has to change and waiting for a lease to expire is the wrong answer.
 - **`— another machine`** → it cannot be reached from here. The board is the only thing you share, so
   say it on the board: `ask`, a `handoff`, or a task note.
+- **`ENDED`** → that is abandoned work, not a peer to negotiate with. Nobody is there to ask, so the
+  decision is yours alone.
+- **two processes on ONE session** → opening a running session in a second local client starts a
+  second process on the same id rather than attaching to the first. Both are alive and both append to
+  one transcript, so **either name reaches the same conversation** — you are handed both precisely
+  because neither is THE address.
+
+### The three answers, and what to do with each
+
+**Nobody.** Carry on. You were told, and a session that was told nothing is not the same as one that
+never looked.
+
+**Somebody, reachable.** Ask them before you scope, not after you collide — one message costs a turn,
+and the collision costs a re-read or a whole gate run. Say what your edit set is and ask for theirs.
+Then **split by GOAL, never by file**: two sessions carving one goal into halves produce two halves
+nobody can ship. If their goal contains yours, hand it over rather than taking it — a `handoff` and a
+message is cheaper than two people converging on one answer from opposite directions. If your edit
+sets genuinely overlap, **sequence and say so**: commit in chunks, tell them when a shared tree is
+clear, and do not interleave.
+
+**Somebody, on another machine.** You cannot reach them at all, so the board is the whole of what you
+share. Put it there — `ask`, a note on the task, a `handoff` — and then decide for yourself. Waiting
+on somebody who cannot hear you is not caution.
+
+**Nothing here refuses you, and nothing here is permission.** Taking always succeeds; you are told
+who else is there and you decide. A harness that argues gets worked around — the one mechanism in
+this repo that refuses produced a hand-written forty-iteration retry loop — so the whole of this is
+*tell clearly, never refuse*.
 
 **The harness never messages anyone.** It reports who and whether they are reachable; opening the
 conversation is your call. A `move` that warns still moves — `next` is the door that declines held