From 5650884927e3c4d240dcaa55903dc688f6e7e712 Mon Sep 17 00:00:00 2001 From: Sigilante Date: Tue, 4 Aug 2026 14:25:19 -0600 Subject: [PATCH] docs: document Gall's five undocumented vane scries Against urbit@08026c84b2. The Gall vane scry arm (sys/vane/gall.hoon:2897-3160) dispatches 15 cares; gall/scry.md documented 10. Adding the missing five, in alphabetical position: %b blocked moves (map term (qeu blocked-move)) gall.hoon:2936 %g flubbed apps (jug ship app=term) gall.hoon:2984 %h halted apps (jug app=term [ship =duct]) gall.hoon:2993 %i flub ducts (map ship duct) gall.hoon:3001 %y live agents (map term yoke) gall.hoon:3138 Types and descriptions are taken from the `+$ state` definition (gall.hoon:78-90) and its own field comments. %y filters the yoke map to live agents only. %g, %h and %i are the observability surface for the Ames/Gall backpressure protocol: %g is which agents have refused a $plea, %h is which flows are halted because an agent is missing or suspended, and %i is the duct used to send %flub notifications per ship. VERIFICATION NOTE, stated plainly: unlike the other PRs in this series, these five were NOT verified by live scry. Each attempt to type a vane-scry path ended up wedging the dojo's line editor -- the `$` path element did not survive send-keys or paste-buffer, and repeated attempts left the input line unusable until the ship was restarted. Rather than keep fighting the terminal or, worse, write a plausible-looking example I had not actually run, the entries are documented from the dispatch conditions and return marks in gall.hoon, which are unambiguous, and the example blocks show only the invocation, not a fabricated product. %y is exercised indirectly and does work: the +vats generator scries it (`.^(yokes ... %gy ...)`) on every run, and +vats was verified live in an earlier PR in this series. Deliberately avoided a cross-PR link: an earlier draft pointed %g at [%halt](../ames/tasks.md#halt), but that anchor is added by the Ames backpressure PR and does not exist on master. If these merged in the wrong order the link would break, so the reference is prose instead. Co-Authored-By: Claude Opus 5 --- content/urbit-os/kernel/gall/scry.md | 82 ++++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) diff --git a/content/urbit-os/kernel/gall/scry.md b/content/urbit-os/kernel/gall/scry.md index f98b7a82..c131ced0 100644 --- a/content/urbit-os/kernel/gall/scry.md +++ b/content/urbit-os/kernel/gall/scry.md @@ -58,6 +58,22 @@ Gall itself provides the special vane-level endpoints listed below. They are org Note you can use `$` to make the last element empty since it won't allow a trailing `/`. Note how in the third example, the empty element is at the *beginning* of the `$spur` and *after* the `$beak`. If you fail to include this empty element, Gall will try route the scry to an agent for handling instead. +### `%b`: blocked moves {#b-blocked-moves} + +A scry with a `%b` care will give you the moves queued for agents that have not been started yet. + +#### Produces + +A `(map term (qeu blocked-move))`, keyed by agent name. + +#### Example + +``` +> .^(* %gb /=//=/$) +``` + +--- + ### `%d`: get desk of app {#d-get-desk-of-app} A scry with a `%d` care and an agent in `q.beak` will give you the desk that agent is on. @@ -130,6 +146,54 @@ A `(map dude @)` where the `@` is the nonce. --- +### `%g`: flubbed apps {#g-flubbed-apps} + +A scry with a `%g` care will give you, per ship, the agents that have refused a `$plea` — the apps for which Gall has given Ames a `%flub`. This is one half of the Ames/Gall backpressure mechanism: a `%flub` causes the corresponding flow to halt. + +#### Produces + +A `(jug ship app=term)`. + +#### Example + +``` +> .^(* %gg /=//=/$) +``` + +--- + +### `%h`: halted apps {#h-halted-apps} + +A scry with an `%h` care will give you, per agent, the ships whose flows are halted because that agent is missing or suspended. + +#### Produces + +A `(jug app=term [ship =duct])`. + +#### Example + +``` +> .^(* %gh /=//=/$) +``` + +--- + +### `%i`: flub ducts {#i-flub-ducts} + +A scry with an `%i` care will give you the duct Gall uses to send `%flub` notifications for each ship. + +#### Produces + +A `(map ship duct)`. + +#### Example + +``` +> .^(* %gi /=//=/$) +``` + +--- + ### `%n`: get nonce of subscription {#n-get-nonce-of-subscription} A scry with a care of `%n`, an agent in `q.beak` and a path of `//[ship]/[agent]/[wire]` will produce the nonce for that subscription. You are unlikely to use this, it's mostly for kernel debugging. @@ -258,6 +322,24 @@ The type returned is the raw `$noun` from the `$page`. If the file has been tomb --- +### `%y`: live agents {#y-live-agents} + +A scry with a `%y` care will give you every running agent and its state. Agents that are not live are excluded from the map. + +#### Produces + +A `(map term yoke)`. + +Note this is the scry the `+vats` generator uses to gather per-desk agent status. + +#### Example + +``` +> .^(* %gy /=//=/$) +``` + +--- + ### `%z`: hash of value at path {#z-hash-of-value-at-path} A scry with a `%z` care and an agent in `q.beak` will get the hash identifier of the value bound at the remote scry path given in the `$spur`.