@manhquy/flow-skill 0.1.0 → 0.2.1

package/skills/flow/harness/flow_harness.py

@@ -20,6 +20,7 @@ import sys
 import _db
 import _domain as D
 import _presence as P
+import graph_executor as G
 
 
 def _flow_lineage_db(argv):
@@ -58,6 +59,23 @@ def _flow_lineage_db(argv):
 def _maybe_forward_to_rust(argv):
     if os.environ.get("FLOW_HARNESS_BACKEND", "python").lower() != "rust":
         return None
+    # graph verbs are flow-only (schema band 014+); the external harness-cli has no such
+    # surface, and on a FRESH db the lineage sniff below would not refuse yet — so the
+    # never-forward set must be explicit, not inferred from DB state. The verb is the
+    # first NON-OPTION token: `--db <path> graph run` must not slip past an argv[0] check.
+    verb, i = None, 0
+    while i < len(argv):
+        tok = argv[i]
+        if tok == "--db":
+            i += 2
+            continue
+        if tok.startswith("-"):
+            i += 1
+            continue
+        verb = tok
+        break
+    if verb == "graph":
+        return None
     conflict = _flow_lineage_db(argv)
     if conflict:
         sys.stderr.write(
@@ -656,6 +674,18 @@ def _events_path(a):
     return os.path.join(os.path.dirname(a._db_path), "events.jsonl")
 
 
+def _canon_sink(p):
+    """Spelling-independent name for a sink path, so 'same file' means 'same key'.
+
+    The same directory reaches us under several spellings: a macOS temp root arrives as
+    both /var/... and /private/var/..., and Windows hands back either an 8.3 short name
+    (C:/Users/RUNNER~1/...) or the long one depending on who resolved it. Keying rows on
+    the raw spelling silently splits one sink into two. realpath collapses the symlink and
+    short-name cases; normcase folds Windows separators and case.
+    """
+    return os.path.normcase(os.path.realpath(p))
+
+
 def _global_log_path():
     return os.path.join(os.path.expanduser("~"), ".claude", "flow", "usage.jsonl")
 
@@ -671,21 +701,33 @@ def _coerce_event(o):
 
 
 def cmd_rollup(con, a):
-    srcs = [_events_path(a)]
+    # (path, key) pairs: `path` is the file read; `key` is the rollup_cursor /
+    # UNIQUE(src,line_no) namespace. They differ only for --src ingests, where a
+    # lifecycle-unique key (--src-key-path + --src-key-tag) prevents a RECYCLED worktree
+    # path from silently swallowing lines 1..N of the next lifecycle's sink.
+    if getattr(a, "src", None):
+        kp = getattr(a, "src_key_path", None) or a.src
+        tag = getattr(a, "src_key_tag", None)
+        key = _canon_sink(kp) + ("#" + tag if tag else "")
+        pairs = [(a.src, key)]
+    else:
+        p = _events_path(a)
+        pairs = [(p, p)]
     if getattr(a, "global_", False):
-        srcs.append(_global_log_path())
+        g = _global_log_path()
+        pairs.append((g, g))
     rolled = skipped = 0
     cols = ["src", "line_no"] + list(USAGE_COLS)
     ph = ",".join("?" for _ in cols)
-    for src in srcs:
-        if not os.path.isfile(src):
+    for src_path, src in pairs:
+        if not os.path.isfile(src_path):
             continue
         cur = con.execute("SELECT last_line FROM rollup_cursor WHERE src=?", (src,)).fetchone()
         last = cur[0] if cur else 0
         # errors="replace": a single invalid byte anywhere in a shared, multi-writer log must
         # not abort the WHOLE rollup - it degrades to a per-line json.loads failure below
         # instead (one bad row skipped, not every row on the file).
-        with open(src, "r", encoding="utf-8", errors="replace") as fh:
+        with open(src_path, "r", encoding="utf-8", errors="replace") as fh:
             text = fh.read()
         lines = text.split("\n")
         lines = lines[:-1]  # drop trailing empty (after final \n) or a partial unterminated last line
@@ -730,15 +772,33 @@ def cmd_rollup(con, a):
     return 0
 
 
+def cmd_graph(con, a):
+    return {
+        "run": G.cmd_graph_run, "record": G.cmd_graph_record, "next": G.cmd_graph_next,
+        "resume": G.cmd_graph_resume, "status": G.cmd_graph_status,
+        "abandon": G.cmd_graph_abandon, "gc": G.cmd_graph_gc, "lint": G.cmd_graph_lint,
+        "cards": G.cmd_graph_cards, "root": G.cmd_graph_root,
+        "session": G.cmd_graph_session, "finish": G.cmd_graph_finish,
+    }[a.graph_cmd](con, a)
+
+
 def cmd_usage(con, a):
     src = _global_log_path() if getattr(a, "global_", False) else _events_path(a)
-    w = "WHERE src=?"
+    # `src=?` matches direct-sink rows; the LIKE arm matches lifecycle-keyed ingests
+    # (`rollup --src-key-path <this-sink> --src-key-tag <branch>#<created_at>` — worktree
+    # telemetry merged at
+    # workspace-remove time). Without it those rows would be write-only: invisible to
+    # usage and unreachable by prune.
+    w = "WHERE (src=? OR src LIKE ? || '#%')"
     # Default-exclude throwaway/test runs so the view reflects real builds. COALESCE handles old
     # rows (ephemeral NULL -> 0); the project-name fallback excludes legacy `tmp.*` runs that
     # predate the field (no log rewrite). `--include-ephemeral` shows everything.
     if not getattr(a, "include_ephemeral", False):
         w += " AND NOT (COALESCE(ephemeral,0)=1 OR project LIKE 'tmp.%')"
-    pr = (src,)
+    # Direct-sink rows are keyed by the path as this process spells it, so `src=?` keeps
+    # matching them verbatim; only the lifecycle arm compares canonically, because those
+    # keys are written by whoever called rollup and their spelling is not ours to choose.
+    pr = (src, _canon_sink(src))
     total = con.execute(f"SELECT COUNT(*) FROM usage_event {w}", pr).fetchone()[0]
     if not total:
         if not getattr(a, "summary", False):   # --summary stays silent on no data (recall appends nothing)
@@ -1003,8 +1063,12 @@ def cmd_prune(con, a):
         os.replace(tmp, src)            # atomic on the same filesystem
         # line numbers changed -> the mirror + cursor for this sink are stale; reset so the next
         # rollup re-ingests the kept lines as line_no 1..K (UNIQUE(src,line_no) stays consistent).
-        con.execute("DELETE FROM usage_event WHERE src=?", (src,))
-        con.execute("DELETE FROM rollup_cursor WHERE src=?", (src,))
+        # Include lifecycle-keyed ingests for this sink (`<sink>#<branch>#<created_at>`):
+        # their line numbers are unrelated to the rewritten file, but the reset contract is
+        # "mirror rows for this sink are rebuilt from the kept lines", and orphaned keyed
+        # rows would be unreachable forever after.
+        con.execute("DELETE FROM usage_event WHERE src=? OR src LIKE ? || '#%'", (src, _canon_sink(src)))
+        con.execute("DELETE FROM rollup_cursor WHERE src=? OR src LIKE ? || '#%'", (src, _canon_sink(src)))
         con.commit()
         print(json.dumps({"sink": src, "kept": len(kept), "dropped": len(lines) - len(kept)}))
     if getattr(a, "global_", False):
@@ -1113,6 +1177,20 @@ def build_parser():
 
     pr = sub.add_parser("rollup", help="ingest JSONL usage sinks into usage_event (idempotent)")
     pr.add_argument("--global", dest="global_", action="store_true", help="also roll up the device-global log")
+    pr.add_argument("--src", help="ingest this JSONL sink instead of the project sink")
+    # Path and tag are SEPARATE flags on purpose. A single pre-joined
+    # "<path>#<branch>#<created_at>" string is not a path, so the Git-Bash/MSYS argument
+    # translation that rewrites POSIX paths into native Windows ones leaves it alone — the
+    # key would then be spelled differently from the sink this python process resolves for
+    # itself, and the rows became write-only: invisible to usage, unreachable by prune.
+    pr.add_argument("--src-key-path", dest="src_key_path",
+                    help="DESTINATION project's events.jsonl path; canonicalized, then used as "
+                         "the cursor/dedupe key prefix so usage/prune group these rows with "
+                         "that project (default: the --src path itself)")
+    pr.add_argument("--src-key-tag", dest="src_key_tag",
+                    help="lifecycle discriminator appended as '#<tag>', e.g. "
+                         "'<branch>#<created_at>' — makes the key unique per worktree "
+                         "lifecycle so a RECYCLED path cannot swallow the next lifecycle's lines")
     pu = sub.add_parser("usage", help="print usage analytics from usage_event")
     pu.add_argument("--global", dest="global_", action="store_true", help="read the device-global log instead of this project")
     pu.add_argument("--json", action="store_true")
@@ -1124,6 +1202,79 @@ def build_parser():
     ppr = sub.add_parser("prune", help="cap each JSONL sink to its last N lines (crash-safe; resets the mirror for that sink)")
     ppr.add_argument("--keep", type=int, help="lines to keep (default 5000)")
     ppr.add_argument("--global", dest="global_", action="store_true", help="also prune the device-global log")
+
+    pg = sub.add_parser("graph", help="graph executor: record/advance journal (flow-owned band 014+)")
+    pgs = pg.add_subparsers(dest="graph_cmd", required=True)
+    g1 = pgs.add_parser("run", help="create an execution; prints its id")
+    g1.add_argument("--project"); g1.add_argument("--kind", required=True, choices=["auto_run", "planning", "card"])
+    g1.add_argument("--topology-version", dest="topology_version", type=int, default=1)
+    g1.add_argument("--topology-hash", dest="topology_hash", default="")
+    g1.add_argument("--story", help="story id tracking handle (TEXT, e.g. C-001)")
+    g2 = pgs.add_parser("record", help="record a step boundary: writes + checkpoint in ONE transaction; prints checkpoint id")
+    g2.add_argument("--execution", required=True); g2.add_argument("--ns", default="")
+    g2.add_argument("--node", required=True)
+    g2.add_argument("--manifest", help="JSON evidence object (parsed + duplicate-key rejected); "
+                                       "prefer the typed flags below so no caller concatenates JSON")
+    g2.add_argument("--gate-exit", dest="gate_exit", type=int, help="gate verdict exit code")
+    g2.add_argument("--gate-cmd", dest="gate_cmd", help="gate command that produced the verdict")
+    g2.add_argument("--card-status", dest="card_status", help="card status token at record time")
+    g2.add_argument("--worktree", help="worktree path (dispatch evidence)")
+    g2.add_argument("--vendor", help="agent vendor (dispatch evidence)")
+    g2.add_argument("--writes", help="JSON array of {task,channel,value} step writes")
+    g2.add_argument("--parent", help="parent checkpoint id (fork chain, e.g. two-strikes attempt 2)")
+    g2.add_argument("--source", default="loop", choices=["input", "loop", "update", "fork"])
+    g2.add_argument("--interrupt", action="store_true", help="open an operator interrupt and pause (exit 3)")
+    g2.add_argument("--prompt", help="interrupt prompt shown to the operator")
+    g2.add_argument("--security-class", dest="security_class", action="store_true")
+    g2.add_argument("--merge", action="store_true",
+                    help="record a merge boundary; the executor COMPUTES the ancestry proof "
+                         "(caller claims are ignored) and records card-abandon when unmerged")
+    g2.add_argument("--branch", help="branch to prove merged (with --merge)")
+    g2.add_argument("--base", help="merge base (default: origin/HEAD, else current branch)")
+    g3 = pgs.add_parser("next", help="next node per topology+journal (exit 3 = complete/paused)")
+    g3.add_argument("--execution", required=True); g3.add_argument("--ns", default="")
+    g3.add_argument("--topology", help="explicit topology JSON path (tests/fixtures; default: "
+                                       "the shipped pin-verified topology + hash policy)")
+    g3.add_argument("--force-retopology", dest="force_retopology", action="store_true",
+                    help="after a skill upgrade changed the topology: fork the chain onto "
+                         "the current topology instead of refusing")
+    g4 = pgs.add_parser("resume", help="resolve an open interrupt (guarded) and resume")
+    g4.add_argument("--execution", required=True)
+    g4.add_argument("--ns", default="", help="select the interrupt by namespace")
+    g4.add_argument("--interrupt-id", dest="interrupt_id",
+                    help="select the exact interrupt (required when several are open)")
+    g4.add_argument("--answer", help='JSON object with a non-empty string "reason"')
+    g4.add_argument("--actor", help="resolving actor id (stored as audit evidence)")
+    g4.add_argument("--target", help="closed-set target the DEBT line must name (C-NNN or NN-stage)")
+    g5 = pgs.add_parser("status", help="execution + latest checkpoint per ns + open interrupts (JSON)")
+    g5.add_argument("--execution", required=True)
+    g6 = pgs.add_parser("abandon", help="terminal-state an execution (kill-at-gate, stale cleanup)")
+    g6.add_argument("--execution", required=True); g6.add_argument("--outcome", help="e.g. killed")
+    gf = pgs.add_parser("finish", help="mark an execution done (lane closed) so the next "
+                                       "feature gets a fresh session and gc can reclaim")
+    gf.add_argument("--execution", required=True); gf.add_argument("--outcome")
+    gf.add_argument("--force", action="store_true", help="close despite open interrupts")
+    g7 = pgs.add_parser("gc", help="purge terminal executions for ONE project (cascade), then "
+                                   "--stale-days marks aged checkpoint-less running as abandoned "
+                                   "(deleted on the NEXT gc, so doctor can surface them first)")
+    g7.add_argument("--stale-days", dest="stale_days", type=int)
+    g7.add_argument("--project", help="project scope (default: basename of FLOW_PROJECT_ROOT)")
+    g9 = pgs.add_parser("cards", help="compile the card DAG: deps-met set + overlap-serialized "
+                                      "ready set + blocked reasons (JSON); rejects dep cycles")
+    g9.add_argument("--active-files", dest="active_files",
+                    help="space/comma list of allowed-file tokens already owned by live worktrees")
+    pgs.add_parser("root", help="print the directory owning this project's durable state "
+                                "(worktree-translated; the one main-tree scope)")
+    gse = pgs.add_parser("session", help="print the project's running auto_run execution, "
+                                         "minting one atomically if absent (no pin file)")
+    gse.add_argument("--project"); gse.add_argument("--no-create", dest="no_create",
+                                                    action="store_true",
+                                                    help="exit 3 instead of minting")
+    gse.add_argument("--kind", choices=["auto_run", "planning"], default="auto_run",
+                     help="session lane: shipping (auto_run) or planning")
+    g8 = pgs.add_parser("lint", help="validate a topology (default: the shipped one incl. pin)")
+    g8.add_argument("--topology", help="explicit topology path (fixtures; skips the pin unless --pin)")
+    g8.add_argument("--pin", help="explicit pin file to verify against")
     return p
 
 
@@ -1147,6 +1298,10 @@ def main(argv):
                 "see harness/README.md for the full contract.\n"
             )
         raise
+    if a.cmd == "graph" and getattr(a, "graph_cmd", "") == "lint":
+        # lint touches no table: skip connect() so CI/linting never mints a DB
+        # (or runs migrations) in the working tree.
+        return G.cmd_graph_lint(None, a) or 0
     con = _db.connect(db_path=a.db)
     a._db_path = a.db or _db.default_db_path()
     dispatch = {
@@ -1155,6 +1310,7 @@ def main(argv):
         "intervention": cmd_intervention, "query": cmd_query,
         "audit": cmd_audit, "propose": cmd_propose,
         "rollup": cmd_rollup, "usage": cmd_usage, "prune": cmd_prune,
+        "graph": cmd_graph,
     }
     try:
         return dispatch[a.cmd](con, a) or 0