premanmcp 1.1.11 → 1.1.13

package/bin/eval_templates.js

@@ -32,6 +32,7 @@ export const SHAPES = new Set([
 export const FREEFORM = "other";
 
 const IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const TOOL_SYMBOL = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$/;
 
 /** Python literal for a JS string. JSON is a subset of Python for these. */
 function lit(value) {
@@ -43,6 +44,37 @@ function litList(values) {
   return `[${(values || []).map((v) => lit(v)).join(", ")}]`;
 }
 
+/**
+ * Python literal for the named tools. Every value came from a model, so each is
+ * checked here; the backend filtered the same rules, and this is the second
+ * gate the templates promise ("every value the model supplied is checked").
+ * Membership in the repository is not checked here -- the caller passes only
+ * the entry file as `tree` -- and a file that is never loaded stays "pending",
+ * which every turn reports as not visible, naming it.
+ */
+function toolsLiteral(tools) {
+  const list = Array.isArray(tools) ? tools : [];
+  const pairs = list.map((tool) => {
+    const file = String(tool?.file || "");
+    const symbol = String(tool?.symbol || "");
+    // The same rules as the backend's `_tools` (flowtest/services/agent_entry_search.py),
+    // plus no control characters. `lit()` quotes everything else safely.
+    if (
+      !file.endsWith(".py")
+      || file.startsWith("/")
+      || file.split("/").includes("..")
+      || [...file].some((ch) => ch.charCodeAt(0) < 0x20)
+    ) {
+      throw new TemplateError(`tool file ${JSON.stringify(file)} is not a repository .py path`);
+    }
+    if (!TOOL_SYMBOL.test(symbol)) {
+      throw new TemplateError(`tool symbol ${JSON.stringify(symbol)} is not a name or Class.method`);
+    }
+    return `(${lit(file)}, ${lit(symbol)})`;
+  });
+  return `[${pairs.join(", ")}]`;
+}
+
 // ── The parts every wrapper shares ──────────────────────────────────────
 
 const HEADER = `# Generated by \`preman eval target\`. Do not edit by hand.
@@ -111,6 +143,312 @@ def preman_selfcheck() -> str:
     return _SYMBOL
 `;
 
+/**
+ * Tool capture for the Python shapes (docs/superpowers/specs/2026-09-30-tool-call-capture-design.md §4).
+ *
+ * Each named tool function is replaced, once, by a recording version -- in its
+ * own module, in every loaded module holding the same object (`from x import
+ * f`), in module-level dicts and lists holding it, and on the class for a
+ * method. Replacing once rather than per turn is what keeps concurrent cases
+ * from racing each other's swaps.
+ *
+ * A turn's calls go into a context variable set in `chat()`. assert-ai runs a
+ * synchronous `chat` through `asyncio.to_thread`, which copies the context, so
+ * concurrent cases stay separate without a lock. A call made in a thread the
+ * agent starts itself sees no turn; it is not guessed onto one -- every turn
+ * open at that moment is reported not visible instead.
+ */
+const PY_CAPTURE = String.raw`
+import contextvars
+import functools
+import inspect
+import json
+import threading
+import time
+
+_TOOLS = %%TOOLS%%
+_turn_calls = contextvars.ContextVar("preman_turn_calls", default=None)
+_open_turns = {}
+_open_lock = threading.Lock()
+_stray_calls = []
+_installed = []
+_missing = {}
+_pending = {}
+_unsupported = {}
+_install_lock = threading.Lock()
+
+
+def _tool_module(file):
+    # Only a module that is already loaded, found by the file it came from.
+    # Importing it here under a name guessed from its path would run the
+    # customer's module-level code a second time, as a second copy the agent
+    # never calls -- the copy that got wrapped would then see no calls at all.
+    # A file that is not loaded yet is left pending and retried next turn.
+    if (_REPO / file).resolve() == _SRC.resolve():
+        return _agent()
+    wanted = (_REPO / file).resolve()
+    for mod in list(sys.modules.values()):
+        where = getattr(mod, "__file__", None)
+        if where:
+            try:
+                if Path(where).resolve() == wanted:
+                    return mod
+            except (OSError, ValueError):
+                continue
+    return None
+
+
+def _jsonable(value):
+    return json.loads(json.dumps(value, ensure_ascii=False, default=str))
+
+
+def _record(name, original, args, kwargs, result):
+    """Build and file the event. Must never raise into the caller ('recorded()',
+    which is standing in for the agent's own call) -- capture failing is not
+    allowed to change what the agent sees. 'default=str' covers values json
+    does not know how to serialise, but not dict keys (a tuple key) or a
+    container that contains itself, both of which raise out of 'json.dumps'
+    regardless. Each of those falls back to 'repr()'; if even that raises, the
+    call is simply not recorded rather than recorded wrong or crashing the turn.
+    """
+    try:
+        try:
+            bound = inspect.signature(original).bind(*args, **kwargs).arguments
+            tool_args = {k: v for k, v in bound.items() if k not in ("self", "cls")}
+        except Exception:
+            tool_args = {"args": list(args), "kwargs": dict(kwargs)}
+        if isinstance(result, str):
+            content = result
+        elif inspect.isgenerator(result):
+            content = "<generator>"
+        else:
+            try:
+                content = json.dumps(result, ensure_ascii=False, default=str)
+            except Exception:
+                content = repr(result)
+        try:
+            args_out = _jsonable(tool_args)
+        except Exception:
+            args_out = {str(k): repr(v) for k, v in tool_args.items()}
+        event = {
+            "role": "tool_result",
+            "tool_name": name,
+            "tool_args": args_out,
+            "content": content,
+        }
+    except Exception:
+        with _open_lock:
+            _stray_calls.append(time.monotonic())
+        return
+
+    calls = _turn_calls.get()
+    if calls is None:
+        with _open_lock:
+            _stray_calls.append(time.monotonic())
+    else:
+        calls.append(event)
+
+
+def _error_text(exc):
+    # str(exc) runs the agent's own __str__, which may itself raise; a new
+    # error here would replace the tool's exception before it is re-raised.
+    name = type(exc).__name__
+    try:
+        return "error: %s: %s" % (name, exc)
+    except Exception:
+        pass
+    try:
+        return "error: %s: %r" % (name, exc)
+    except Exception:
+        return "error: %s" % name
+
+
+def _recording(name, original):
+    if inspect.iscoroutinefunction(original):
+        @functools.wraps(original)
+        async def recorded(*args, **kwargs):
+            try:
+                result = await original(*args, **kwargs)
+            except BaseException as exc:
+                _record(name, original, args, kwargs, _error_text(exc))
+                raise
+            _record(name, original, args, kwargs, result)
+            return result
+    else:
+        @functools.wraps(original)
+        def recorded(*args, **kwargs):
+            try:
+                result = original(*args, **kwargs)
+            except BaseException as exc:
+                _record(name, original, args, kwargs, _error_text(exc))
+                raise
+            _record(name, original, args, kwargs, result)
+            return result
+    recorded.__preman_original__ = original
+    return recorded
+
+
+def _replace_everywhere(original, recorded):
+    for mod in list(sys.modules.values()):
+        try:
+            space = getattr(mod, "__dict__", None)
+            if not isinstance(space, dict):
+                continue
+            for key, value in list(space.items()):
+                if value is original:
+                    space[key] = recorded
+                elif isinstance(value, dict):
+                    for inner, item in list(value.items()):
+                        if item is original:
+                            value[inner] = recorded
+                elif isinstance(value, list):
+                    for index, item in enumerate(value):
+                        if item is original:
+                            value[index] = recorded
+        except Exception:
+            # One odd entry in sys.modules (a proxy whose __dict__ or .items()
+            # raises) must not fail the whole install and take every other
+            # tool down with it.
+            continue
+
+
+def _install():
+    # Serialized, and the agent loaded first, unconditionally, inside the
+    # lock -- PY_LOADER's own _agent() has no lock of its own, so two threads
+    # reaching it at once can each exec_module a distinct module object, and
+    # whichever one _turn() ends up calling is not reliably the one whose
+    # functions got wrapped below. Taking the lock here and loading the agent
+    # before touching _TOOLS means every chat() (every chat() calls _install()
+    # first) either does that one load-and-wrap or blocks until it is done, so
+    # _turn() always sees the same, already-wrapped module -- concurrent first
+    # calls included.
+    with _install_lock:
+        _agent()
+        for file, symbol in _TOOLS:
+            key = "%s:%s" % (file, symbol)
+            if key in _installed:
+                continue
+            mod = _tool_module(file)
+            if mod is None:
+                _pending[key] = "module not loaded yet"
+                continue
+            _pending.pop(key, None)
+            owner_name, _, method = symbol.partition(".")
+            owner = getattr(mod, owner_name, None)
+            if owner is None:
+                _missing[key] = "%s not defined" % owner_name
+                continue
+            if method:
+                if not inspect.isclass(owner):
+                    # owner_name names an instance ('support = Support()'),
+                    # not the class -- setattr on it would shadow the method
+                    # with a plain function on one object, and calling it would
+                    # raise a missing-argument TypeError the agent never had.
+                    _missing[key] = "%s.%s is not a method on a class" % (owner_name, method)
+                    continue
+                raw = inspect.getattr_static(owner, method, None)
+                if raw is None:
+                    _missing[key] = "%s has no %s" % (owner_name, method)
+                    continue
+                if isinstance(raw, (staticmethod, classmethod)):
+                    wrapped = type(raw)(_recording(method, raw.__func__))
+                elif inspect.isfunction(raw):
+                    wrapped = _recording(method, raw)
+                else:
+                    # A property or other descriptor: replacing it with a
+                    # plain function would change what the attribute even is.
+                    _missing[key] = "%s.%s is not a method on a class" % (owner_name, method)
+                    continue
+                setattr(owner, method, wrapped)
+            elif not inspect.isfunction(owner):
+                # A framework tool object (LangChain/crewAI '@tool', OpenAI
+                # Agents '@function_tool'), a callable instance or a class:
+                # swapping it for a plain function would remove the attributes
+                # and type the agent relies on. Left exactly as it is.
+                _missing.pop(key, None)
+                _unsupported[key] = "not a plain function (%s)" % type(owner).__name__
+                continue
+            elif getattr(owner, "__preman_original__", None) is None:
+                _replace_everywhere(owner, _recording(owner_name, owner))
+            _missing.pop(key, None)
+            _unsupported.pop(key, None)
+            _installed.append(key)
+
+
+def _tool_names(installed):
+    return [key.split(":", 1)[1].split(".")[-1] for key in installed]
+
+
+def _begin_turn():
+    calls = []
+    token = _turn_calls.set(calls)
+    marker = object()
+    with _open_lock:
+        _open_turns[id(marker)] = time.monotonic()
+    return token, marker, calls
+
+
+def _end_turn(token, marker, calls):
+    _turn_calls.reset(token)
+    now = time.monotonic()
+    with _open_lock:
+        started = _open_turns.pop(id(marker))
+        stray = any(started <= t <= now for t in _stray_calls)
+        oldest = min(_open_turns.values(), default=now)
+        _stray_calls[:] = [t for t in _stray_calls if t >= oldest]
+    # A snapshot under the same lock _install() mutates them under, so a turn
+    # that lands between two of _install()'s steps on another thread cannot
+    # read a torn "some tools installed, matching missing entry not popped yet"
+    # state.
+    with _install_lock:
+        installed = list(_installed)
+        missing = sorted(_missing)
+        unseen = dict(_pending)
+        unseen.update(_unsupported)
+        not_watched = dict(_missing)
+        not_watched.update(unseen)
+    # "recorded" only when every named tool is installed: a tool that is not
+    # watched could have run without being seen, so a zero would not be a
+    # confirmed zero.
+    if not _TOOLS:
+        state, reason = "not_visible", "discovery named no tool functions"
+    elif not installed and not unseen:
+        state, reason = "not_visible", "no named tool function could be found"
+    elif not_watched:
+        state, reason = "not_visible", "not watched: " + "; ".join(
+            "%s (%s)" % (k, v) for k, v in sorted(not_watched.items())
+        )
+    elif stray:
+        state, reason = "not_visible", "a tool ran outside any turn, in a thread the agent started"
+    else:
+        state, reason = "recorded", ""
+    return {
+        "state": state,
+        "source": "wrapped",
+        "watched": _tool_names(installed),
+        "missing": missing,
+        "reason": reason,
+    }
+
+
+def preman_selfcheck() -> str:
+    # _install() first: it takes _install_lock and loads the agent itself
+    # before touching _TOOLS. Calling _target() first would load the agent
+    # outside that lock, racing a concurrent call's locked load.
+    _install()
+    _target()
+    # Only a missing tool fails: a pending one (its module is not loaded yet)
+    # or an unsupported one (not a plain function) is reported per turn as
+    # "not visible" instead, and the agent still runs.
+    if _missing:
+        raise RuntimeError(
+            "tool functions named by discovery were not found: "
+            + "; ".join("%s (%s)" % (k, v) for k, v in sorted(_missing.items()))
+            + ". Re-run 'preman eval target'."
+        )
+    return _SYMBOL
+`;
+
 /**
  * The reply, normalised.
  *
@@ -162,13 +500,41 @@ def _text(value):
         if isinstance(found, str) and found.strip():
             return found
     return "" if value is None else str(value)
+`;
 
+/** `chat()` for the shapes that do not capture tool calls. */
+const PY_CHAT = String.raw`
 
 def chat(message: str, history: list | None = None) -> dict:
     reply, events = _turn(message, history or [])
     return {"response": _text(reply), "events": list(events or [])}
 `;
 
+/** `chat()` for `cli_subprocess`: the agent reports its own calls through a file. */
+const PY_CHAT_REPORTED = String.raw`
+
+def chat(message: str, history: list | None = None) -> dict:
+    reply, events, capture = _turn(message, history or [])
+    return {"response": _text(reply), "events": list(events or []), "tool_capture": capture}
+`;
+
+/** `chat()` for the Python shapes: the turn runs inside a capture window. */
+const PY_CHAT_CAPTURING = String.raw`
+
+def chat(message: str, history: list | None = None) -> dict:
+    _install()
+    token, marker, calls = _begin_turn()
+    try:
+        reply, events = _turn(message, history or [])
+    finally:
+        capture = _end_turn(token, marker, calls)
+    return {
+        "response": _text(reply),
+        "events": list(events or []) + calls,
+        "tool_capture": capture,
+    }
+`;
+
 // ── One `_turn` per shape ───────────────────────────────────────────────
 
 const TURNS = {
@@ -420,9 +786,11 @@ for await (const line of createInterface({ input: process.stdin })) {
  * and shows up in process listings.
  */
 const CLI_SUBPROCESS = String.raw`
+import json
 import os
 import shutil
 import subprocess
+import tempfile
 from pathlib import Path
 
 _REPO = Path(__file__).resolve().parent.parent
@@ -530,20 +898,64 @@ def _prompt(message, history):
     return "\n\n".join(lines)
 
 
+def _not_visible(reason):
+    return {"state": "not_visible", "source": "events_file", "watched": [], "missing": [], "reason": reason}
+
+
+def _read_events(path):
+    """The tool calls the agent wrote to PREMAN_TOOL_EVENTS_FILE, one JSON line each.
+
+    The agent creates the file even when it calls nothing, so a missing file
+    means "this agent does not report", never "it called no tools".
+    """
+    if not os.path.exists(path):
+        return [], _not_visible("the agent did not create PREMAN_TOOL_EVENTS_FILE, so its tool calls are not reported")
+    events = []
+    with open(path, encoding="utf-8") as handle:
+        for line in handle:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                item = json.loads(line)
+            except ValueError:
+                return events, _not_visible("PREMAN_TOOL_EVENTS_FILE held a line that is not JSON")
+            if not isinstance(item, dict) or not item.get("tool_name"):
+                return events, _not_visible("a line in PREMAN_TOOL_EVENTS_FILE has no tool_name")
+            args = item.get("tool_args")
+            content = item.get("content", "")
+            events.append({
+                "role": "tool_result",
+                "tool_name": str(item["tool_name"]),
+                "tool_args": args if isinstance(args, dict) else {},
+                "content": content if isinstance(content, str) else json.dumps(content, ensure_ascii=False, default=str),
+            })
+    return events, {"state": "recorded", "source": "events_file", "watched": [], "missing": [], "reason": ""}
+
+
 def _turn(message, history):
     argv = [_binary()] + list(_ARGV[1:])
-    done = subprocess.run(
-        argv,
-        input=_prompt(message, history),
-        capture_output=True,
-        text=True,
-        cwd=str(_REPO),
-        timeout=_TIMEOUT,
-    )
-    if done.returncode != 0:
-        tail = (done.stderr or "").strip()[-600:]
-        raise RuntimeError("%s exited %s: %s" % (_ARGV[0], done.returncode, tail))
-    return done.stdout.strip(), []
+    # One file per turn: each turn is its own process, so nothing can be filed
+    # under the wrong turn.
+    folder = tempfile.mkdtemp(prefix="preman-tools-")
+    events_path = os.path.join(folder, "tool_events.jsonl")
+    try:
+        done = subprocess.run(
+            argv,
+            input=_prompt(message, history),
+            capture_output=True,
+            text=True,
+            cwd=str(_REPO),
+            timeout=_TIMEOUT,
+            env=dict(os.environ, PREMAN_TOOL_EVENTS_FILE=events_path),
+        )
+        if done.returncode != 0:
+            tail = (done.stderr or "").strip()[-600:]
+            raise RuntimeError("%s exited %s: %s" % (_ARGV[0], done.returncode, tail))
+        events, capture = _read_events(events_path)
+    finally:
+        shutil.rmtree(folder, ignore_errors=True)
+    return done.stdout.strip(), events, capture
 `;
 
 // ── Assembly ────────────────────────────────────────────────────────────
@@ -596,7 +1008,7 @@ export function buildWrapper(found, { tree = [] } = {}) {
 
   if (shape === "cli_subprocess") {
     return {
-      shim: header + CLI_SUBPROCESS.replace("%%COMMAND%%", litList(command)) + PY_NORMALISE,
+      shim: header + CLI_SUBPROCESS.replace("%%COMMAND%%", litList(command)) + PY_NORMALISE + PY_CHAT_REPORTED,
       bridge: "",
     };
   }
@@ -615,7 +1027,8 @@ export function buildWrapper(found, { tree = [] } = {}) {
       + NODE_BRIDGE
           .replace("%%NODE_RUNTIME%%", lit(runtime))
           .replace("%%ENTRY_SYMBOL%%", lit(symbol))
-      + PY_NORMALISE;
+      + PY_NORMALISE
+      + PY_CHAT;
     const bridge = NODE_SIDE
       .replace(/%%NODE_ENTRY%%/g, lit("../" + nodeEntry))
       .replace(/%%ENTRY_SYMBOL%%/g, lit(symbol));
@@ -631,12 +1044,20 @@ export function buildWrapper(found, { tree = [] } = {}) {
     turn = turn.replace("%%METHOD%%", lit(method));
   }
 
-  const shim = header
-    + PY_LOADER
-        .replace("%%ENTRY_FILE%%", lit(entryFile))
-        .replace("%%ENTRY_SYMBOL%%", lit(symbol))
-    + turn
-    + PY_NORMALISE;
+  const loader = PY_LOADER
+    .replace("%%ENTRY_FILE%%", lit(entryFile))
+    .replace("%%ENTRY_SYMBOL%%", lit(symbol));
+
+  // langgraph reads tool calls out of the graph's own messages (§5.1 of the
+  // design), not by wrapping functions, so it keeps the plain `chat()`.
+  if (shape === "langgraph") {
+    return { shim: header + loader + turn + PY_NORMALISE + PY_CHAT, bridge: "" };
+  }
+  // Checked only for the shapes that use it, so a tool path this shape never
+  // reads cannot fail the build. Every value is checked before it is quoted
+  // into the template, so a tool value a model invented cannot interpolate.
+  const tools = toolsLiteral(found?.tools);
+  const shim = header + loader + PY_CAPTURE.replace("%%TOOLS%%", tools) + turn + PY_NORMALISE + PY_CHAT_CAPTURING;
   return { shim, bridge: "" };
 }
 
@@ -660,6 +1081,9 @@ export function buildFreeform(found, { tree = [], turnSource = "" } = {}) {
   }
   const body = String(turnSource || "").trimEnd();
   if (!body.trim()) throw new TemplateError("no conversion body was returned");
+  // Computed before any text is built, so a tool value a model invented does
+  // not get the chance to interpolate into a template.
+  const tools = toolsLiteral(found?.tools);
 
   const header = HEADER
     .replace("%%SHAPE%%", "other")
@@ -676,9 +1100,11 @@ export function buildFreeform(found, { tree = [], turnSource = "" } = {}) {
     + PY_LOADER
         .replace("%%ENTRY_FILE%%", lit(entryFile))
         .replace("%%ENTRY_SYMBOL%%", lit(symbol))
+    + PY_CAPTURE.replace("%%TOOLS%%", tools)
     + "\n\ndef _turn(message, history):\n"
     + `    ${symbol} = _target()\n`
     + body + "\n"
-    + PY_NORMALISE;
+    + PY_NORMALISE
+    + PY_CHAT_CAPTURING;
   return { shim, bridge: "" };
 }

package/bin/hook.js

@@ -190,6 +190,11 @@ export function hookIsBehind(invocation) {
   return isOlderRelease(pinned, running);
 }
 
+/** A path as one POSIX shell word, safe for any character a home directory allows. */
+function shellSingleQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
 function hookBody(invocation) {
   // `exec` is deliberately absent: we want the wrapper to survive the CLI exiting
   // non-zero and still exit 0 itself.
@@ -201,14 +206,29 @@ ${MARKER}
 # Managed by PreMan. Runs the local endpoint suite before the push leaves.
 # Advisory unless this repository opted into blocking: only exit code
 # ${BLOCK_EXIT_CODE} stops a push, so a crash or a timeout still lets it through.
+#
+# PREMAN_HOOK_BIN is the bin directory PreMan was installed in when this hook
+# was written. A hook is generated once and then runs for months, and a version
+# manager switching Node takes that whole directory off PATH -- after which
+# this hook printed "not on PATH, checks skipped" on every single push, forever
+# and silently, which is the worst available outcome for a tool whose only job
+# is checking pushes. git does not run a login shell, so nvm's own PATH setup
+# is not here to recover it either. Recording the directory costs nothing and
+# makes the second attempt the one that works.
 if [ -z "\${PREMAN_SKIP_HOOK}" ]; then
+  PREMAN_HOOK_BIN=${shellSingleQuote(path.dirname(process.execPath))}
   PREMAN_HOOK=1 ${invocation} verify --pre-push --timeout ${HOOK_TIMEOUT_SECONDS}
   preman_status=$?
+  if [ "$preman_status" -eq 127 ] && [ -d "$PREMAN_HOOK_BIN" ]; then
+    PATH="$PREMAN_HOOK_BIN:$PATH" PREMAN_HOOK=1 ${invocation} verify --pre-push --timeout ${HOOK_TIMEOUT_SECONDS}
+    preman_status=$?
+  fi
   if [ "$preman_status" -eq ${BLOCK_EXIT_CODE} ]; then
     exit ${BLOCK_EXIT_CODE}
   fi
   if [ "$preman_status" -eq 127 ]; then
-    printf '[preman] the PreMan CLI is not on PATH; push checks skipped\\n' >&2
+    printf '[preman] the PreMan CLI is not on PATH, so push checks were skipped.\\n' >&2
+    printf '[preman] run: preman hook install --force\\n' >&2
   elif [ "$preman_status" -ne 0 ]; then
     printf '[preman] checks skipped (advisory, exit %s)\\n' "$preman_status" >&2
   fi

package/bin/integrations.js

@@ -587,13 +587,19 @@ async function showDesktopSignedIn(openDesktopSignedIn, args, creds, stopOpening
       `PreMan was already open and kept its previous sign-in.\n` +
         `  Quit and reopen it to switch${email ? ` to ${email}` : ""}.\n`
     );
+  } else if (opened.state === "launch-failed") {
+    // The installer has already printed what open said and what to do about it,
+    // so this step adds nothing by repeating it -- but it must not fall through
+    // to the line below, which claims the app is up. It said "Opened PreMan" on
+    // top of a Gatekeeper refusal, and then the walk signed off with a line
+    // about the app being on screen.
   } else {
     // Either the session could not be handed over or this app is too old to take
     // it up. Say so rather than let the customer wonder why they are looking at
     // a login screen.
     process.stdout.write("Opened PreMan \u2014 sign in with the account you just used.\n");
   }
-  return opened.state !== "not-installed";
+  return opened.state !== "not-installed" && opened.state !== "launch-failed";
 }
 
 /** One step heading, in the one format the whole walk uses. */
@@ -869,7 +875,11 @@ export async function onboardCommand(
             "Not a git repository, so there is nothing to hook here.\n" +
               `Run '${cliInvocation()} hook install' inside your API repo.\n`
           );
-          return;
+          // Returning nothing means "done" to the summary, so the walk that
+          // had just explained it could not install a hook signed off with a
+          // tick against Push checks five lines later. The last line of a walk
+          // is the one people keep, and it was the one saying the opposite.
+          return { state: "skipped", detail: "not a git repository" };
         }
         throw err;
       }
@@ -878,7 +888,7 @@ export async function onboardCommand(
       // nothing would leave the customer believing their pushes are checked.
       if (result.action === "conflict" || result.action === "unproven") {
         process.stdout.write(`Not installed: ${result.detail}\n  ${result.path}\n`);
-        return;
+        return { state: "skipped", detail: result.detail };
       }
 
       // One line, like every other step. The pinned invocation and the skip
@@ -1020,7 +1030,13 @@ export async function onboardCommand(
     const result = outcome.get(step.name);
     if (!result) continue;
     if (result.state === "done") process.stdout.write(`${MARK.ok()} ${step.name}\n`);
-    else if (result.state === "skipped") process.stdout.write(`${MARK.skip()} ${step.name} (skipped)\n`);
+    else if (result.state === "skipped") {
+      // The reason belongs on the line. "(skipped)" against a step the customer
+      // said yes to reads as a bug in the walk rather than a condition on their
+      // machine, and the condition is usually the thing they can act on.
+      const why = result.detail ? ` (${result.detail})` : " (skipped)";
+      process.stdout.write(`${MARK.skip()} ${step.name}${why}\n`);
+    }
     else process.stdout.write(`${MARK.fail()} ${step.name}: ${result.detail}\n`);
   }
   // The app is on screen by the time this prints, so telling them to go and open