Merge main (hq ADR 0266) into the mesh-cli answer, and close what the confirmation review found

- The generic command verb only reads now (commandReads) and terminal-only
  commands are refused through any verb (terminalOnly). mesh-cli's
  ordinary line made neither check: `node account`, `token issue` and
  `secret export` from another node would have run. It now meets both, in
  the one function the command verb shares.
- The serving controller marks itself and its children never the terminal
  (ADR 0266); a line mesh-cli runs as the terminal drops that mark and
  carries MESH_CLI_TERMINAL, so it reads as the terminal it is.
- Two withholding tests searched the answer's text while JSON writes bytes
  as base64, so they held nothing. They search both now, each proved by
  disabling what it guards (Shown, the bus withholding, `calls` via Get).
- The control-node refusal is tested through the assign and unassign acts.

internal/catalogue/agent_account_test.go

@@ -0,0 +1,119 @@
+package catalogue
+
+import (
+	"testing"
+)
+
+// The account agents run as (novox/hq ADR 0266): a module names it as a machine fact — the agent account
+// where the node names one, the operator's otherwise — and asks the node-engine to judge it never to become
+// root only where it is the agents' own.
+
+func TestTheAgentAccountFactFallsBackToTheOperatorAndIsNeverRootOnlyWhenItsOwn(t *testing.T) {
+	facts := machineFacts(Resolution{Node: "anchor", Account: "ops"}, nil, "")
+	if facts["agent-account"] != "ops" || facts["agent-home"] != "/home/ops" || facts["agent-root"] != "" {
+		t.Errorf("with no agent account named, agents run as the operator: %v", facts)
+	}
+	facts = machineFacts(Resolution{Node: "anchor", Account: "ops", AccountHome: "/srv/ops"}, nil, "")
+	if facts["agent-home"] != "/srv/ops" {
+		t.Errorf("the operator's stated home is the agent's home when they are one account: %v", facts)
+	}
+	facts = machineFacts(Resolution{Node: "anchor", Account: "ops", AgentAccount: "agent"}, nil, "")
+	if facts["agent-account"] != "agent" || facts["agent-home"] != "/home/agent" || facts["agent-root"] != RootNever {
+		t.Errorf("a named agent account is the agents', never root: %v", facts)
+	}
+	if facts["account"] != "ops" {
+		t.Errorf("the operator account is still the operator's: %v", facts)
+	}
+	facts = machineFacts(Resolution{Node: "anchor", AgentAccount: "agent", AgentAccountHome: "/var/lib/agent"}, nil, "")
+	if facts["agent-home"] != "/var/lib/agent" || facts["agent-root"] != RootNever {
+		t.Errorf("an agent account with a stated home on a machine with no operator: %v", facts)
+	}
+	if _, has := machineFacts(Resolution{Node: "anchor"}, nil, "")["agent-account"]; has {
+		t.Error("a machine with no account at all names an agent account")
+	}
+}
+
+// The agent's module, in the shape the catalogue's declares it: the account, never root where it is its
+// own; its directory under that home, owned by it.
+const agentModule = `{"module": "agent", "version": "1", "resources": [
+  {"id": "account", "type": "user", "name": "${machine:agent-account}", "home": "${machine:agent-home}",
+   "root": "${machine:agent-root}"},
+  {"id": "home", "type": "directory", "path": "${machine:agent-home}/.agent", "mode": "0700",
+   "owner": "${machine:agent-account}"}
+]}`
+
+func TestTheAgentAccountIsDeclaredNeverRootOnlyToAnEngineThatJudgesIt(t *testing.T) {
+	m, err := ParseManifest([]byte(agentModule))
+	if err != nil {
+		t.Fatal(err)
+	}
+	compose := func(r Resolution, with Rendering) (user, home map[string]any) {
+		t.Helper()
+		r.Node, r.Modules = "anchor", []Manifest{m}
+		out, err := r.Declaration(with)
+		if err != nil {
+			t.Fatal(err)
+		}
+		return fileNamed(out, "agent.account"), fileNamed(out, "agent.home")
+	}
+
+	user, home := compose(Resolution{Account: "ops", AgentAccount: "agent"}, Rendering{JudgesRoot: true})
+	if user["name"] != "agent" || user[RootField] != RootNever || user["home"] != "/home/agent" {
+		t.Errorf("an engine that judges root is sent the agent account never to become root: %v", user)
+	}
+	if home["path"] != "/home/agent/.agent" || home["owner"] != "agent" {
+		t.Errorf("the agent's directory is under its own home, its own: %v", home)
+	}
+
+	user, _ = compose(Resolution{Account: "ops", AgentAccount: "agent", AgentAccountHome: "/srv/agent"}, Rendering{JudgesRoot: true})
+	if user["home"] != "/srv/agent" {
+		t.Errorf("an agent account named with a home of its own is made there: %v", user)
+	}
+
+	user, _ = compose(Resolution{Account: "ops", AgentAccount: "agent"}, Rendering{})
+	if _, sent := user[RootField]; sent || user["name"] != "agent" {
+		t.Errorf("an older engine, which parses strictly, is sent root: %v", user)
+	}
+
+	user, home = compose(Resolution{Account: "ops"}, Rendering{JudgesRoot: true})
+	if _, sent := user[RootField]; sent || user["name"] != "ops" {
+		t.Errorf("where agents run as the operator, root asserts nothing and is not sent: %v", user)
+	}
+	if home["path"] != "/home/ops/.agent" || home["owner"] != "ops" {
+		t.Errorf("with no agent account, the agent's directory is the operator's: %v", home)
+	}
+}
+
+func TestTheRuntimeIsToldTheAgentAccount(t *testing.T) {
+	with := Rendering{ArtifactStore: "anchor.internal:5101",
+		Needed: map[string]map[string]string{RuntimeModule: {"broker": "sealed-credential"}}}
+	envOf := func(r Resolution) map[string]string {
+		t.Helper()
+		r.Node, r.Modules = "anchor", []Manifest{aToolsModule(t, "nftables", "tools/index.js"), theRuntime(t)}
+		out, err := r.Declaration(with)
+		if err != nil {
+			t.Fatal(err)
+		}
+		process := fileNamed(out, RuntimeModule+"."+RuntimeProcessID())
+		if process == nil {
+			t.Fatal("no runtime process was composed")
+		}
+		return process["env"].(map[string]string)
+	}
+	env := envOf(Resolution{Account: "ops", AgentAccount: "agent"})
+	if env[RuntimeAgentAccount] != "agent" || env[RuntimeAgentHome] != "/home/agent" || env[RuntimeOperatorAccount] != "ops" {
+		t.Errorf("the runtime is not told whom agents run as: %v", env)
+	}
+	env = envOf(Resolution{Account: "ops"})
+	if env[RuntimeAgentAccount] != "ops" || env[RuntimeAgentHome] != "/home/ops" {
+		t.Errorf("with no agent account, agents run as the operator: %v", env)
+	}
+	env = envOf(Resolution{})
+	if _, set := env[RuntimeAgentAccount]; set {
+		t.Errorf("a machine with no account names an agent account: %v", env)
+	}
+	if problems := bundleEnvProblems("x", Artifact{Name: "b", Kind: ArtifactBundle, Loads: []string{"x"},
+		Env: map[string]string{RuntimeAgentAccount: "me"}}); len(problems) == 0 {
+		t.Error("a bundle may tell the runtime whom agents run as")
+	}
+}

internal/catalogue/build.go

@@ -399,7 +399,7 @@ func versionOf(digest string) string {
 // telling the runtime what it is, which is the mesh's to say (novox/hq ADR 0192).
 var bundleEnvWords = map[string]bool{
 	RuntimeToolModules: true, RuntimeBrokerFile: true, RuntimeOperatorAccount: true,
-	RuntimeOperatorHome: true, RuntimeToolEnv: true,
+	RuntimeOperatorHome: true, RuntimeToolEnv: true, RuntimeAgentAccount: true, RuntimeAgentHome: true,
 }
 
 // bundleEnvProblems says what is wrong with what a bundle says it is given (novox/hq ADR 0192):

internal/catalogue/declaration.go

@@ -241,6 +241,31 @@ type Rendering struct {
 	// refuses a field it does not know, whole — so to it the field is not sent, and what it runs is
 	// judged by liveness alone.
 	ReadsHealth bool
+
+	// JudgesRoot says this machine's node-engine judges a user's declared `root` (novox/hq ADR 0266: its
+	// statement's contract is link.RootContract or later). To an older, strict engine the field is not
+	// sent, and the account it names is not judged — which the self-check says, as not judged.
+	JudgesRoot bool
+}
+
+// RootField is a user resource's field saying the account must never become root without a person
+// (novox/hq ADR 0266).
+const RootField = "root"
+
+// rootInto composes a user's `root` for the node-engine: taken away when it asserts nothing (empty — a
+// machine where agents run as the operator) or when the engine is older than the field and parses
+// strictly; kept as "never" otherwise.
+func rootInto(resource map[string]any, with Rendering) {
+	if resource["type"] != "user" {
+		return
+	}
+	value, has := resource[RootField]
+	if !has {
+		return
+	}
+	if s, _ := value.(string); s == "" || !with.JudgesRoot {
+		delete(resource, RootField)
+	}
 }
 
 // machinePort is where a module's port lives on this machine, or the port itself when the mesh has
@@ -981,6 +1006,9 @@ func (r Resolution) compose(with Rendering, owner map[string]string,
 			// How it is ready, in the node-engine's words: its endpoint as the port this machine
 			// published it on — or not sent at all to an engine older than the field (ADR 0240).
 			healthInto(copied, m, with)
+			// And a user's `root` (novox/hq ADR 0266): sent only when it asserts something, to an engine
+			// that judges it.
+			rootInto(copied, with)
 			// The account's environment and every module's shell code, where this module holds the
 			// seat that places them (novox/hq ADR 0203, ADR 0204). Gathered from every module on
 			// the node, as the jails are, and **last of every placeholder pass**: shell code is a

internal/catalogue/machine_into_files.go

@@ -78,9 +78,47 @@ func machineFacts(r Resolution, names map[string]string, meshRange string) map[s
 		out["account"] = r.Account
 		out["account-home"] = accountHomeOf(r.Account, r.AccountHome)
 	}
+	// The account agents run as here, and whether it must never become root (novox/hq ADR 0266). The agent
+	// account where the node names one; the operator account otherwise, so a module writing the agent's
+	// home names one fact on every machine. `agent-root` is "never" only for an account of the agents' own:
+	// the user resource naming it then asks the node-engine to judge it, and on a machine where agents run
+	// as the operator it is empty, asserting nothing — the operator's account may become root there.
+	if agent, home := r.agentAccount(); agent != "" {
+		out["agent-account"] = agent
+		out["agent-home"] = home
+		out["agent-root"] = ""
+		if r.AgentAccount != "" {
+			out["agent-root"] = RootNever
+		}
+	}
 	return out
 }
 
+// RootNever is what a user resource's `root` says of an account that must never become root without a
+// person (novox/hq ADR 0266); the node-engine judges it.
+const RootNever = "never"
+
+// agentAccount is the account agents run as on this machine and its home: the agent account when the node
+// names one (novox/hq ADR 0266), else the operator account; empty when neither is known.
+func (r Resolution) agentAccount() (string, string) {
+	if r.AgentAccount != "" {
+		return r.AgentAccount, agentHomeOf(r.AgentAccount, r.AgentAccountHome)
+	}
+	if r.Account != "" {
+		return r.Account, accountHomeOf(r.Account, r.AccountHome)
+	}
+	return "", ""
+}
+
+// agentHomeOf is where the agent account's home is: what was stored, or /home/<account>. Never /root: the
+// agent account is never root.
+func agentHomeOf(account, home string) string {
+	if home != "" {
+		return home
+	}
+	return "/home/" + account
+}
+
 // accountHomeOf is where an account's home is: what was stored, or the derived default — /root for
 // root, /home/<account> otherwise. The one place the default is written, so a fact and the store
 // cannot disagree about it.
@@ -105,8 +143,12 @@ func machineInto(resource map[string]any, facts map[string]string, module string
 	// (novox/hq to-be 29), the same reason its content names ${machine:address}. And the name a
 	// `user` shape sets the login shell of, and the user a user-scoped unit or a process runs as:
 	// the shell module makes the operator's account its holder's login shell, and the desktop's
-	// watchers run as that account (novox/hq ADR 0176, ADR 0177) — neither can name the person.
-	for _, field := range []string{"path", "owner", "content", "name", "user"} {
+	// watchers run as that account (novox/hq ADR 0176, ADR 0177) — neither can name the person. And a
+	// user's `root`: the agent's module declares the account agents run as with ${machine:agent-root},
+	// "never" only where that account is the agents' own (novox/hq ADR 0266), and its `home`, so an account
+	// the operator named with a home of its own is made there (${machine:agent-home}); the node-engine reads a
+	// user's home only when it creates the account, so an existing one is never moved.
+	for _, field := range []string{"path", "owner", "content", "name", "user", "root", "home"} {
 		s, ok := resource[field].(string)
 		if !ok {
 			continue

internal/catalogue/resolve.go

@@ -32,6 +32,11 @@ type Node struct {
 	// to-be 29). What a home-scoped file is owned by and what ${machine:account} resolves to.
 	Account     string
 	AccountHome string
+	// AgentAccount is the login agents run as here when it is not the operator's, AgentAccountHome its
+	// home when not derived (novox/hq ADR 0266). What ${machine:agent-account} resolves to; empty means
+	// agents run as the operator account.
+	AgentAccount     string
+	AgentAccountHome string
 }
 
 // World is what the rest of the mesh already has.
@@ -134,6 +139,10 @@ type Resolution struct {
 	// here without a store lookup.
 	Account     string
 	AccountHome string
+	// AgentAccount and AgentAccountHome are the account agents run as here when it is not the
+	// operator's, and its home (novox/hq ADR 0266); empty when agents run as the operator account.
+	AgentAccount     string
+	AgentAccountHome string
 	// Capabilities are the machine's, as its profile reported them, carried from the node so a
 	// contribution placed only where the machine has something (`if-capability`, novox/hq ADR 0255)
 	// is decided here without a store lookup.
@@ -703,7 +712,8 @@ func Resolve(catalogue map[string]Manifest, assigned []string, node Node, world
 	}
 
 	resolution := Resolution{Node: node.Name, At: node.At, PublicDomain: node.PublicDomain,
-		Account: node.Account, AccountHome: node.AccountHome, Capabilities: node.Capabilities,
+		Account: node.Account, AccountHome: node.AccountHome, AgentAccount: node.AgentAccount,
+		AgentAccountHome: node.AgentAccountHome, Capabilities: node.Capabilities,
 		Because: because, Needs: needs, Unhostable: unhostable, Kept: kept}
 	for _, n := range providersFirst(order, catalogue) {
 		resolution.Modules = append(resolution.Modules, catalogue[n])

internal/catalogue/runtime.go

@@ -83,6 +83,11 @@ const (
 	RuntimeBrokerFile      = "MESH_BROKER_FILE"
 	RuntimeOperatorAccount = "MESH_OPERATOR_ACCOUNT"
 	RuntimeOperatorHome    = "MESH_OPERATOR_HOME"
+	// RuntimeAgentAccount and RuntimeAgentHome are the account agents run as on the machine and its home
+	// (novox/hq ADR 0266): the agent account where the node names one, the operator account otherwise.
+	// The agent's module writes the agent's home from them; absent where neither account is known.
+	RuntimeAgentAccount = "MESH_AGENT_ACCOUNT"
+	RuntimeAgentHome    = "MESH_AGENT_HOME"
 	// RuntimeToolEnv is every served module's composed environment, as JSON (novox/hq ADR 0192):
 	// {"<module>": {"<word>": "<value>"}}. The runtime takes it at start, removes it from its own
 	// environment and hands each module's words to that module's bundles alone. In the unit, so a
@@ -215,6 +220,10 @@ func (r Resolution) runtimeProcess(with Rendering) (map[string]any, error) {
 		env[RuntimeOperatorHome] = accountHomeOf(r.Account, r.AccountHome)
 		process["user"] = r.Account
 	}
+	if agent, home := r.agentAccount(); agent != "" {
+		env[RuntimeAgentAccount] = agent
+		env[RuntimeAgentHome] = home
+	}
 	// Routed through the artifact store as this network reaches it now, like everything the mesh
 	// built; refused with the same words when there is no store to route through.
 	if err := artifactsInto(process, RuntimeModule, with); err != nil {

internal/catalogue/verbs.go

@@ -237,9 +237,9 @@ var ControllerVerbs = []Verb{
 			"node":   "the machine that runs the module",
 			"module": "the module's name",
 		}, []string{"node", "module"})},
-	{Name: "token", Description: "Issue a one-time token for a machine to join with. Give the public half of the " +
-		"tunnel key the machine made (`nox-mesh-host key`): the machine is given its address and made a peer of " +
-		"the hub, and joins through the tunnel. The token is shown once, in the answer.",
+	{Name: "token", Description: "Refused through a verb since novox/hq ADR 0266: the one-time token a machine " +
+		"joins with is answered to its caller, and whoever may call a verb includes agents. Issue it at the " +
+		"controller's terminal: `mesh-controller token issue --new <name> --overlay-key <public half>`.",
 		Input: schema(map[string]string{
 			"node":        "a machine the mesh already has a record for",
 			"new":         "or the name of a machine to create the record for",
@@ -267,10 +267,14 @@ var ControllerVerbs = []Verb{
 			"list": "\"preferences\": every module's preferences — key, default and why — and the value on each " +
 				"machine it is assigned to with where it comes from; module and node narrow it (novox/hq ADR 0262)",
 		}, nil, "clear", "replace", "history")},
-	{Name: "command", Description: "Run one command line of the controller's own, as you would type it at its " +
-		"shell — `node account g14 jochen`, `node show ace`, `module list` — and answer what it printed. The " +
-		"generic verb beside the named ones (novox/hq ADR 0154): everything the binary can do, without a verb " +
-		"per command. Any node may call any tool (ADR 0175), so nothing is held back here.",
+	{Name: "command", Description: "Run one reading command line of the controller's own, as you would type it at " +
+		"its shell — `node show ace`, `module list`, `plans`, `conditions show <key>` — and answer what it " +
+		"printed. The generic verb beside the named ones (novox/hq ADR 0154), and since ADR 0266 it only reads: " +
+		"status, version, help, seats, healers, hand-acts, durations, collection, images, artifacts, data, builds, " +
+		"queue, plan, plans (not stop/close/go), doctor (not run), conditions list/show/history, node list/show, " +
+		"module list, settings show/preferences, retire list, cleanup list, delivery plan/walks, bus, mirrors (not " +
+		"--record/--confirm). What writes has its named verb; what sets a key, issues a credential or a token, or " +
+		"accepts, recovers or exports a secret is the controller's terminal's alone.",
 		Input: schema(map[string]string{
 			"command": "the command line, as the controller's binary takes it; quotes group a word with spaces",
 		}, []string{"command"})},

internal/facts/facts.go

@@ -131,6 +131,10 @@ type Machine struct {
 	// home is when that is not the derived one.
 	Account     string `json:"account,omitempty"`
 	AccountHome string `json:"account-home,omitempty"`
+	// AgentAccount is the account agents run as there when it is not the operator's (a pseudonym), and
+	// AgentAccountHome its home when not derived (novox/hq ADR 0266).
+	AgentAccount     string `json:"agent-account,omitempty"`
+	AgentAccountHome string `json:"agent-account-home,omitempty"`
 	// PublicDomain is the domain it answers for, its labels replaced.
 	PublicDomain string `json:"public-domain,omitempty"`
 	// Assigned is every module assigned there.

internal/inventory/agent_account_test.go

@@ -0,0 +1,93 @@
+package inventory
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"testing"
+)
+
+// The agent account (novox/hq ADR 0266): recorded and read back with every node, its home derived when
+// not stated, cleared by an empty name — and refused when it is root, the operator's own account, or no
+// login at all, because each of those would say agents have an account of their own while they do not.
+func TestAgentAccountIsRecordedAndRefusedWhereItWouldNotConfine(t *testing.T) {
+	inv := ForTest(t)
+	ctx := context.Background()
+	if _, err := inv.AddNode(ctx, "anchor"); err != nil {
+		t.Fatal(err)
+	}
+	if err := inv.SetAccount(ctx, "anchor", "operator", ""); err != nil {
+		t.Fatal(err)
+	}
+
+	n, err := inv.NodeByName(ctx, "anchor")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if n.AgentAccount != "" || n.AgentHome() != "" {
+		t.Fatalf("a node that names none has agent account %q, home %q", n.AgentAccount, n.AgentHome())
+	}
+
+	if err := inv.SetAgentAccount(ctx, "anchor", "agent", ""); err != nil {
+		t.Fatal(err)
+	}
+	n, _ = inv.NodeByName(ctx, "anchor")
+	if n.AgentAccount != "agent" || n.AgentHome() != "/home/agent" {
+		t.Fatalf("agent account %q, home %q; want agent, /home/agent", n.AgentAccount, n.AgentHome())
+	}
+	all, err := inv.Nodes(ctx)
+	if err != nil || len(all) != 1 || all[0].AgentAccount != "agent" {
+		t.Fatalf("the listing does not carry the agent account: %+v %v", all, err)
+	}
+
+	if err := inv.SetAgentAccount(ctx, "anchor", "agent", "/srv/agent"); err != nil {
+		t.Fatal(err)
+	}
+	if n, _ = inv.NodeByName(ctx, "anchor"); n.AgentHome() != "/srv/agent" {
+		t.Fatalf("the stated home is %q", n.AgentHome())
+	}
+
+	for _, c := range []struct{ account, home, says string }{
+		{"root", "", "may not run as root"},
+		{"operator", "", "operator account"},
+		{"Agent", "", "not a login name"},
+		{"9agent", "", "not a login name"},
+		{"agent", "relative", "absolute"},
+		{"postgres", "", "service account"},
+		{"systemd-network", "", "service account"},
+		{"showcase", "", "service account"},
+		{"", "/home/x", "without an agent account"},
+	} {
+		err := inv.SetAgentAccount(ctx, "anchor", c.account, c.home)
+		if err == nil || !strings.Contains(err.Error(), c.says) {
+			t.Errorf("%q %q: %v; want a refusal saying %q", c.account, c.home, err, c.says)
+		}
+	}
+	if n, _ = inv.NodeByName(ctx, "anchor"); n.AgentAccount != "agent" {
+		t.Fatalf("a refusal changed the record: %q", n.AgentAccount)
+	}
+
+	// The other direction: the operator account may not be named as the agent account either.
+	if err := inv.SetAccount(ctx, "anchor", "agent", ""); err == nil || !strings.Contains(err.Error(), "agent account") {
+		t.Fatalf("the operator account named as the agent account: %v; want a refusal", err)
+	}
+	if n, _ = inv.NodeByName(ctx, "anchor"); n.Account != "operator" {
+		t.Fatalf("a refusal changed the operator account: %q", n.Account)
+	}
+
+	if err := inv.SetAgentAccount(ctx, "anchor", "", ""); err != nil {
+		t.Fatal(err)
+	}
+	if err := inv.SetAccount(ctx, "anchor", "agent", ""); err != nil {
+		t.Fatalf("with the agent account cleared, the name is free: %v", err)
+	}
+	if err := inv.SetAccount(ctx, "anchor", "operator", ""); err != nil {
+		t.Fatal(err)
+	}
+	if n, _ = inv.NodeByName(ctx, "anchor"); n.AgentAccount != "" || n.AgentAccountHome != "" {
+		t.Fatalf("clearing left %q %q", n.AgentAccount, n.AgentAccountHome)
+	}
+	if err := inv.SetAgentAccount(ctx, "nowhere", "agent", ""); !errors.Is(err, ErrNoSuchNode) {
+		t.Fatalf("an unknown node: %v", err)
+	}
+}

internal/inventory/catalogue.go

@@ -169,6 +169,25 @@ func (i *Inventory) RegisterModule(ctx context.Context, m catalogue.Manifest, fr
 	return nil
 }
 
+// SourceIdentity is the forge's id of the repository a module is registered from, 0 when none is recorded.
+func (i *Inventory) SourceIdentity(ctx context.Context, module string) (int64, error) {
+	var id *int64
+	err := i.store.Pool().QueryRow(ctx, `select source_repo_id from module where name = $1`, module).Scan(&id)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return 0, fmt.Errorf("%w: %s", ErrNoSuchModule, module)
+	}
+	if err != nil || id == nil {
+		return 0, err
+	}
+	return *id, nil
+}
+
+// SetSourceIdentity records the forge's id of the repository a module is registered from; 0 records none.
+func (i *Inventory) SetSourceIdentity(ctx context.Context, module string, id int64) error {
+	_, err := i.store.Pool().Exec(ctx, `update module set source_repo_id = nullif($2::bigint, 0) where name = $1`, module, id)
+	return err
+}
+
 // hasModule is whether the catalogue holds a module of that name.
 func (i *Inventory) hasModule(ctx context.Context, name string) (bool, error) {
 	var one int

internal/inventory/gate.go

@@ -7,6 +7,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"strings"
 	"time"
 
 	"github.com/jackc/pgx/v5"
@@ -169,6 +170,12 @@ func (i *Inventory) PreviousBuild(ctx context.Context, module, commit string, fa
 		if b.ID == failed.ID || (commit != "" && b.Commit != commit) {
 			continue
 		}
+		// Only a build of the repository the failed build was made from — the module's, since its take-in
+		// registered it (novox/hq ADR 0266): a build of the module's name from another repository is recorded
+		// and was never registered, and putting it back would register it now.
+		if failed.Repository != "" && !sameRepositoryAs(b.Repository, failed.Repository) {
+			continue
+		}
 		if !failed.AskedOrAt().IsZero() && !b.AskedOrAt().Before(failed.AskedOrAt()) {
 			continue
 		}
@@ -190,6 +197,14 @@ func (i *Inventory) PreviousBuild(ctx context.Context, module, commit string, fa
 	return Build{}, false, nil
 }
 
+// sameRepositoryAs says two recorded repositories are one, however their case or `.git` is spelled.
+func sameRepositoryAs(a, b string) bool {
+	trim := func(s string) string {
+		return strings.TrimSuffix(strings.TrimRight(strings.ToLower(strings.TrimSpace(s)), "/"), ".git")
+	}
+	return trim(a) == trim(b)
+}
+
 // RestoreModule puts a module's registered build back to an earlier one: its manifest, the commit it
 // was built from, and when it was asked — as now, so the build that failed its gate, asked before, can
 // never register over it again (issue 219's order). The source's head is left where the merge moved it:

internal/inventory/health.go

@@ -31,6 +31,9 @@ type ResourceHealth struct {
 	// Account is the account whose own service manager runs it, or the account a resource of kind account
 	// is (novox/hq ADR 0254).
 	Account string `json:"account,omitempty"`
+	// Root is "never" on an account verdict that judged whether the account can become root without a
+	// person (novox/hq ADR 0266).
+	Root string `json:"root,omitempty"`
 }
 
 // NodeHealth is a machine's newest statement, as kept.

internal/inventory/migrations/0083-a-node-names-the-account-its-agents-run-as.sql

@@ -0,0 +1,13 @@
+-- A node names the account its agents run as (novox/hq ADR 0266).
+--
+-- On the control node every agent session ran as the operator's account, which may become root without
+-- a password: any agent there could become root without a person. The decision is an account of the
+-- agents' own, without sudo, beside the operator's, who keeps theirs. Stated by the operator at the
+-- controller's terminal, like the operator account (migration 0036), and never by a verb or a setting,
+-- so no agent can change which account it is.
+--
+-- Empty rather than null, as the operator account is: empty is a real state, "agents run as the
+-- operator's account here" — a workstation's today. The home is stored only when it is not
+-- /home/<account>; empty means derive it.
+alter table node add column agent_account text not null default '';
+alter table node add column agent_account_home text not null default '';

internal/inventory/migrations/0084-a-build-asked-at-the-terminal-says-so.sql

@@ -0,0 +1,18 @@
+-- A build asked at the controller's terminal says so (novox/hq ADR 0266).
+--
+-- A build's outcome registers its module, and a module is what the next push sends: a module named `sudo`
+-- built from a repository an agent made would grant whoever wrote it root on every node it is assigned.
+-- So an outcome may register a module only from the repository the catalogue already builds it from — or,
+-- for a module new to the catalogue, from a repository the catalogue already builds another module from.
+-- Anything else — a module moved to another repository, a new module from a new repository — is the
+-- operator's, at the controller's terminal. This column is how the take-in tells: true only for a build
+-- request kept by a `build` or `replay --register` run at the terminal, never through a verb (whoever may
+-- call a verb includes agents). False for every request kept before this column existed.
+alter table build_request add column at_terminal boolean not null default false;
+
+-- And which repository a module is registered from, by the forge's own id for it (novox/hq ADR 0266): a name
+-- is not an identity. A repository deleted and made again under the same name is another repository, with
+-- none of the protection the first had until someone sets it; its outcome must not register as the module's.
+-- Recorded when a build of it is registered from the mesh's own forge; null until then, and for a source the
+-- forge does not hold.
+alter table module add column source_repo_id bigint;

internal/inventory/migrations/0085-the-controller-keeps-when-a-root-search-began-pending.sql

@@ -0,0 +1,9 @@
+-- The controller keeps when it first saw an agent account's root verdict waiting for the node-engine's search
+-- for setuid programs (novox/hq ADR 0266), cleared by the next complete verdict.
+--
+-- The self-check does not raise `agent-can-become-root` while that search is within its bound, so a restart is
+-- not an urgent condition each time. The node-engine's own "since" starts again at every restart: an agent
+-- that restarted the engine in a loop kept the condition quiet for ever. This time is the controller's, kept
+-- across the engine's restarts and its own, so the quiet ends once the bound has passed since the search first
+-- read as pending, however often the engine started again.
+alter table node add column agent_root_pending_since timestamptz;

internal/inventory/nodes.go

@@ -9,6 +9,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"regexp"
 	"sort"
 	"strings"
 	"time"
@@ -69,6 +70,14 @@ type Node struct {
 	Account     string
 	AccountHome string
 
+	// AgentAccount is the login agents run as on this machine when it is not the operator's — `agent`
+	// on the control node (novox/hq ADR 0266): an account of their own, without sudo, so no agent there
+	// can become root without a person. Empty means agents run as the operator account. Stated at the
+	// controller's terminal only, never by a verb or a setting. AgentAccountHome is its home when not
+	// /home/<account>; empty means derive it.
+	AgentAccount     string
+	AgentAccountHome string
+
 	// HostVersion is the version of the host this machine reported running (novox/hq 04-ISSUES/087).
 	// Empty when it has not said since the mesh began keeping it — which is not the same as running
 	// no host, so nothing derives "behind" from an empty one.
@@ -91,6 +100,17 @@ func (n Node) Home() string {
 	}
 }
 
+// AgentHome is the agent account's home, derived when not stored; empty when no agent account is named.
+func (n Node) AgentHome() string {
+	if n.AgentAccount == "" {
+		return ""
+	}
+	if n.AgentAccountHome != "" {
+		return n.AgentAccountHome
+	}
+	return "/home/" + n.AgentAccount
+}
+
 // Silent is how long since this node was last heard from, and whether it ever was.
 func (n Node) Silent() (time.Duration, bool) {
 	if n.LastSeen.IsZero() {
@@ -147,14 +167,14 @@ func (i *Inventory) AddNodeAs(ctx context.Context, name string, adopted bool) (N
 // nodeColumns and scanNode are the one reading of a node row, so every way of finding a node
 // says whether it is adopted.
 const nodeColumns = `id, name, created, last_seen, adopted, adopted_since, account, account_home,
-	host_version`
+	agent_account, agent_account_home, host_version`
 
 func scanNode(row pgx.Row) (Node, error) {
 	var n Node
 	var seen, since *time.Time
 	var host *string
 	if err := row.Scan(&n.ID, &n.Name, &n.Created, &seen, &n.Adopted, &since,
-		&n.Account, &n.AccountHome, &host); err != nil {
+		&n.Account, &n.AccountHome, &n.AgentAccount, &n.AgentAccountHome, &host); err != nil {
 		return Node{}, err
 	}
 	if host != nil {
@@ -172,7 +192,23 @@ func scanNode(row pgx.Row) (Node, error) {
 // SetAccount records the operator account on a node — its human login — and optionally where that
 // account's home is (novox/hq to-be 29). An empty home means the mesh derives it. Clearing the
 // account (empty name) is allowed: a machine may stop having a known operator.
+//
+// **Never the node's agent account** (novox/hq ADR 0266): the operator account may become root, and the
+// agent account exists so agents cannot; naming the one as the other gives agents root. Refused here as
+// SetAgentAccount refuses the other direction.
 func (i *Inventory) SetAccount(ctx context.Context, node, account, home string) error {
+	account = strings.TrimSpace(account)
+	if account != "" {
+		n, err := i.NodeByName(ctx, node)
+		if err != nil {
+			return err
+		}
+		if n.AgentAccount != "" && n.AgentAccount == account {
+			return fmt.Errorf("%s is %s's agent account: the operator account may become root, and agents run as "+
+				"%s so that they cannot (novox/hq ADR 0266); clear the agent account first "+
+				"(node agent-account %s --clear) if the operator is to log in as it", account, node, account, node)
+		}
+	}
 	tag, err := i.store.Pool().Exec(ctx,
 		`update node set account = $1, account_home = $2 where name = $3`, account, home, node)
 	if err != nil {
@@ -184,6 +220,86 @@ func (i *Inventory) SetAccount(ctx context.Context, node, account, home string)
 	return nil
 }
 
+// loginName is what a login may be called: what useradd accepts by default, lower case, a letter or
+// an underscore first.
+var loginName = regexp.MustCompile(`^[a-z_][a-z0-9_-]{0,31}$`)
+
+// SetAgentAccount records the account agents run as on a node, and optionally its home (novox/hq ADR
+// 0266). An empty account clears it: agents run as the operator account again.
+//
+// **Refused, rather than recorded and judged later:** root, which is the very thing the account exists
+// to keep agents from; the node's operator account, which may become root without a password and is
+// what agents ran as before — naming it here would say the agents have an account of their own while
+// they do not; and a name no machine would accept as a login.
+func (i *Inventory) SetAgentAccount(ctx context.Context, node, account, home string) error {
+	account, home = strings.TrimSpace(account), strings.TrimSpace(home)
+	if account == "" && home != "" {
+		return errors.New("a home without an agent account says nothing; name the account too")
+	}
+	if account != "" {
+		if err := AgentAccountRefusal(account, home); err != nil {
+			return err
+		}
+		n, err := i.NodeByName(ctx, node)
+		if err != nil {
+			return err
+		}
+		if n.Account != "" && n.Account == account {
+			return fmt.Errorf("%s is %s's operator account: agents would run as the operator, who may become "+
+				"root; clear the agent account instead (node agent-account %s --clear)", account, node, node)
+		}
+	}
+	tag, err := i.store.Pool().Exec(ctx,
+		`update node set agent_account = $1, agent_account_home = $2 where name = $3`, account, home, node)
+	if err != nil {
+		return err
+	}
+	if tag.RowsAffected() == 0 {
+		return fmt.Errorf("%w: %s", ErrNoSuchNode, node)
+	}
+	return nil
+}
+
+// serviceAccounts are the system and service accounts a machine of the mesh has, or a module of the
+// catalogue declares (showcase, and the accounts ADR 0259 gives the router and the channels). The controller
+// cannot read a machine's user database, so this list is the controller's half; the node-engine's half is
+// refusing to take an existing account below the first login uid as one that must never become root.
+var serviceAccounts = map[string]bool{
+	"root": true, "bin": true, "daemon": true, "sys": true, "adm": true, "nobody": true, "mail": true,
+	"ftp": true, "http": true, "www-data": true, "git": true, "sshd": true, "dbus": true, "polkitd": true,
+	"postgres": true, "docker": true, "nats": true, "redis": true, "uuidd": true, "dnsmasq": true,
+	"avahi": true, "rtkit": true, "colord": true, "geoclue": true, "tss": true, "alpm": true, "usbmux": true,
+	"showcase": true, "messenger": true, "telegram": true,
+}
+
+// serviceAccount says whether a name is a system or service account: one of the list, or a name of
+// systemd's own (systemd-…).
+func serviceAccount(name string) bool {
+	return serviceAccounts[name] || strings.HasPrefix(name, "systemd-")
+}
+
+// AgentAccountRefusal is why an agent account cannot be named, or nil: root, a malformed login, or a
+// home that is not an absolute path.
+func AgentAccountRefusal(account, home string) error {
+	if account == "root" {
+		return errors.New("agents may not run as root: the agent account exists to keep them from it " +
+			"(novox/hq ADR 0266)")
+	}
+	if !loginName.MatchString(account) {
+		return fmt.Errorf("%q is not a login name: lower case letters, digits, _ and -, a letter or _ first, "+
+			"at most 32", account)
+	}
+	if serviceAccount(account) {
+		return fmt.Errorf("%q is a system or service account a machine or a module already has: the agent "+
+			"account is one the mesh creates for agents alone, which nothing else runs as or owns files as "+
+			"(novox/hq ADR 0266); name a new one, such as agent", account)
+	}
+	if home != "" && !strings.HasPrefix(home, "/") {
+		return fmt.Errorf("the agent account's home %q is not an absolute path", home)
+	}
+	return nil
+}
+
 // Nodes are every node record, oldest first.
 func (i *Inventory) Nodes(ctx context.Context) ([]Node, error) {
 	rows, err := i.store.Pool().Query(ctx,
@@ -1176,3 +1292,24 @@ func (i *Inventory) Sequence(ctx context.Context, id string) (int64, error) {
 	}
 	return *n, nil
 }
+
+// RootSearchPending keeps when the controller first saw this node's agent account waiting for the node-engine's
+// setuid search (novox/hq ADR 0266) and answers it: the first time it is seen since the last complete verdict,
+// at, kept; seen again, what was kept. Kept across the engine's restarts and the controller's own.
+func (i *Inventory) RootSearchPending(ctx context.Context, node string, at time.Time) (time.Time, error) {
+	var since time.Time
+	err := i.store.Pool().QueryRow(ctx,
+		`update node set agent_root_pending_since = coalesce(agent_root_pending_since, $2)
+		  where name = $1 returning agent_root_pending_since`, node, at).Scan(&since)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return time.Time{}, fmt.Errorf("%w: %s", ErrNoSuchNode, node)
+	}
+	return since, err
+}
+
+// RootSearchJudged forgets when a search began pending: a complete verdict came.
+func (i *Inventory) RootSearchJudged(ctx context.Context, node string) error {
+	_, err := i.store.Pool().Exec(ctx,
+		`update node set agent_root_pending_since = null where name = $1 and agent_root_pending_since is not null`, node)
+	return err
+}

internal/inventory/pending.go

@@ -38,6 +38,9 @@ type BuildRequest struct {
 	// unknown. Read as in flight until its outcome or its bound.
 	OutcomeUnknown string
 	At             time.Time
+	// AtTerminal says the request was asked at the controller's terminal, never through a verb (novox/hq ADR
+	// 0266): what lets its outcome register a module from a repository the catalogue does not build it from.
+	AtTerminal bool
 }
 
 // Name is the module this request is expected to register, read from its directory: the last element of
@@ -73,16 +76,31 @@ func (i *Inventory) RecordBuildRequest(ctx context.Context, a BuildRequest) erro
 		notAsked = &a.NotAsked
 	}
 	if _, err := i.store.Pool().Exec(ctx,
-		`insert into build_request (id, repository, seat, source_path, ref, commit_hash, asked_for, not_asked, asked_at)
-		 values ($1, $2, $3, $4, $5, $6, $7, $8, $9)
+		`insert into build_request (id, repository, seat, source_path, ref, commit_hash, asked_for, not_asked, asked_at,
+		                            at_terminal)
+		 values ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
 		 on conflict (id) do nothing`,
-		a.ID, a.Repository, a.Seat, strings.Trim(a.Path, "/"), a.Ref, a.Commit, a.For, notAsked, at); err != nil {
+		a.ID, a.Repository, a.Seat, strings.Trim(a.Path, "/"), a.Ref, a.Commit, a.For, notAsked, at,
+		a.AtTerminal); err != nil {
 		return err
 	}
 	_, err := i.store.Pool().Exec(ctx, `delete from build_request where asked_at < $1`, time.Now().Add(-KeptFor))
 	return err
 }
 
+// BuildRequestByID is the build request kept under this id, and whether one was kept.
+func (i *Inventory) BuildRequestByID(ctx context.Context, id string) (BuildRequest, bool, error) {
+	var a BuildRequest
+	err := i.store.Pool().QueryRow(ctx,
+		`select id, repository, seat, source_path, ref, commit_hash, asked_for, at_terminal, asked_at
+		   from build_request where id = $1`, id).Scan(&a.ID, &a.Repository, &a.Seat, &a.Path, &a.Ref, &a.Commit,
+		&a.For, &a.AtTerminal, &a.At)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return BuildRequest{}, false, nil
+	}
+	return a, err == nil, err
+}
+
 // MarkNotAsked says a kept build request was never handed over: the words are kept, unless its outcome was
 // heard first.
 func (i *Inventory) MarkNotAsked(ctx context.Context, id, why string) error {

internal/link/meshcli_test.go

@@ -2,6 +2,7 @@ package link
 
 import (
 	"context"
+	"encoding/base64"
 	"encoding/json"
 	"sort"
 	"strings"
@@ -203,13 +204,13 @@ func TestAMeshCLIRecordKeepsNeitherItsLineNorItsAnswerOnTheBus(t *testing.T) {
 	asked, _ := json.Marshal(CLIAsked{Line: []string{"settings", "set", "x", `{"password":"s3cret"}`}, Account: "op"})
 	l.serveCall(CLISeat, "laptop", asked, "_INBOX.node.laptop.abcdefghijklmnopqrstuv",
 		func(context.Context, json.RawMessage) (any, error) {
-			return CLIAnswer{Stdout: []byte("token s3cret-join")}, nil
+			return CLIAnswer{Stdout: []byte("s3cret-join")}, nil
 		},
 		a.respond, nil)
 	_ = a.only()
 	close(writes)
 	for c := range writes {
-		if strings.Contains(string(c.Args), "s3cret") || strings.Contains(string(c.Answer), "s3cret") {
+		if carries(c.Args, "s3cret") || carries(c.Answer, "s3cret-join") {
 			t.Fatalf("the bus was sent %s / %s", c.Args, c.Answer)
 		}
 		if !strings.Contains(string(c.Args), "settings") || !strings.Contains(string(c.Args), `"op"`) {
@@ -234,7 +235,7 @@ func TestCallsNeverShowsAMeshCLILinesAnswer(t *testing.T) {
 	if err != nil || !found {
 		t.Fatalf("the line is not shown at all: %v %v", found, err)
 	}
-	if strings.Contains(string(shown.Answer), "s3cret-join") {
+	if carries(shown.Answer, "s3cret-join") {
 		t.Fatalf("calls shows a mesh-cli line's answer: %s", shown.Answer)
 	}
 	b := newAnswers(t)
@@ -246,3 +247,19 @@ func TestCallsNeverShowsAMeshCLILinesAnswer(t *testing.T) {
 		t.Fatalf("another call's answer is withheld: %s", shown.Answer)
 	}
 }
+
+// carries says whether a record holds a secret as text or as the base64 JSON writes bytes in: a line's output is
+// bytes, so a search for its text alone finds nothing whatever the record keeps (review of ADR 0272).
+func carries(body []byte, secret string) bool {
+	return strings.Contains(string(body), secret) ||
+		strings.Contains(string(body), base64.StdEncoding.EncodeToString([]byte(secret)))
+}
+
+// The two tests above hold what they claim: each fails when the protection it names is taken away.
+func TestTheWithholdingTestsHoldSomething(t *testing.T) {
+	// The answer as a mesh-cli line's record would carry it, were it kept: the search finds it.
+	body, _ := json.Marshal(map[string]any{"result": CLIAnswer{Stdout: []byte("s3cret-join")}})
+	if !carries(body, "s3cret-join") {
+		t.Fatalf("a record carrying the answer is not found carrying it: %s", body)
+	}
+}

internal/link/protocol.go

@@ -8,6 +8,7 @@ package link
 
 import (
 	"encoding/base64"
+	"github.com/novox/mesh-host/rootsearch"
 	"strconv"
 	"strings"
 	"time"
@@ -420,6 +421,29 @@ const LivenessContract = 1
 // because an older one parses strictly and would refuse the whole declaration for it.
 const ReadinessContract = 2
 
+// RootContract is the statement of an engine that also judges a user's declared `root` (novox/hq ADR 0266):
+// whether an account declared never to become root without a person can — uid 0, a group that grants root,
+// a sudo rule, a secret of the mesh it may read. Only to such an engine is the field sent: an older one
+// parses strictly and would refuse the whole declaration for it.
+const RootContract = 3
+
+// ReasonRoot starts the reason of an account verdict that found a way to root (ADR 0266); the node-engine's
+// own words (mesh-host internal/accounts ReasonRoot).
+const ReasonRoot = "can become root without a person"
+
+// ReasonRootPending starts the reason of an account verdict the node-engine cannot give yet because its search
+// for setuid programs, started when the engine started, has not finished: not judged yet, said as such, never a
+// pass. The node-engine's own words (mesh-host rootsearch.ReasonPending), read from it rather than copied.
+const ReasonRootPending = rootsearch.ReasonPending
+
+// RootSearchBound is the longest the node-engine lets one search for setuid programs run (mesh-host
+// rootsearch.Bound): the one value both read.
+const RootSearchBound = rootsearch.Bound
+
+// RootNever is the value of a user's `root`, and of a verdict's Root, that the account must never become
+// root without a person (ADR 0266).
+const RootNever = "never"
+
 // Health is one statement of a machine's long-running resources (to-be 48 §4): in every report, as the
 // event HealthSubject between reports on each change, and again every minute while one is not healthy.
 // The node-engine's own (mesh-host internal/link Health); a test on each side holds the field names.
@@ -550,6 +574,10 @@ type ResourceHealth struct {
 	// manager, and the account itself for a resource of kind KindAccount (novox/hq ADR 0254). Empty from an
 	// engine older than that, and for anything the machine's own manager or runtime runs.
 	Account string `json:"account,omitempty"`
+	// Root is "never" on a verdict of kind KindAccount whose account is declared never to become root
+	// without a person (novox/hq ADR 0266): the engine judged that too, and a healthy verdict says it cannot.
+	// Empty from an engine older than RootContract, and on every other verdict.
+	Root string `json:"root,omitempty"`
 }
 
 // HealthSaid is the health event's body: the machine and its statement. The machine is read from the