Probe: the placement files with every seat held once (issue 1126); not to be merged

.gitignore

@@ -41,4 +41,3 @@ checks/placement/placement
 # Built by their modules' build step (issue 1577), never committed.
 modules/forticlient/cmd/forticlient-tools/forticlient-tools
 modules/networkmanager/uplink-tools
-checks/words/words

checks/nobinaries/nobinaries.go

@@ -1,4 +1,4 @@
-// Package nobinaries refuses a compiled program anywhere in the repository (issue 1577; first a checks/ binary slipped past a modules/-only rule): it is build output, made by the module's build step,
+// Package nobinaries refuses a compiled program under modules/ (issue 1577): it is build output, made by the module's build step,
 // and `go build` in a module's folder writes one beside go.mod where `git add -A` takes it.
 package nobinaries
 
@@ -27,10 +27,10 @@ func Kind(head []byte) string {
 	return ""
 }
 
-// Files are the files of the catalogue's root that the change holds, anywhere: the tracked ones when the root is a git
-// checkout (an ignored binary a local build left is not the change's), else every file there but .git's.
+// Files are the files of the catalogue's root that the change holds under modules/: the tracked ones when the root is a git
+// checkout (an ignored binary a local build left is not the change's), else every file there.
 func Files(root string) ([]string, error) {
-	cmd := exec.Command("git", "-C", root, "ls-files", "-z")
+	cmd := exec.Command("git", "-C", root, "ls-files", "-z", "--", "modules")
 	if out, err := cmd.Output(); err == nil && len(out) > 0 {
 		var files []string
 		for _, f := range strings.Split(strings.TrimRight(string(out), "\x00"), "\x00") {
@@ -41,16 +41,10 @@ func Files(root string) ([]string, error) {
 		return files, nil
 	}
 	var files []string
-	err := filepath.WalkDir(root, func(p string, d os.DirEntry, err error) error {
-		if err != nil {
+	err := filepath.WalkDir(filepath.Join(root, "modules"), func(p string, d os.DirEntry, err error) error {
+		if err != nil || d.IsDir() || !d.Type().IsRegular() {
 			return err
 		}
-		if d.IsDir() && d.Name() == ".git" {
-			return filepath.SkipDir
-		}
-		if d.IsDir() || !d.Type().IsRegular() {
-			return nil
-		}
 		rel, _ := filepath.Rel(root, p)
 		files = append(files, rel)
 		return nil

checks/nobinaries/nobinaries_test.go

@@ -2,7 +2,6 @@ package nobinaries
 
 import (
 	"os"
-	"os/exec"
 	"path/filepath"
 	"testing"
 )
@@ -17,7 +16,6 @@ func TestFindNamesEachCompiledProgramAndNothingElse(t *testing.T) {
 		"modules/e/short":       []byte("\x7f"),
 		"modules/f/empty":       {},
 		"modules/g/Foo.class":   {0xca, 0xfe, 0xba, 0xbe, 0, 0, 0, 52}, // Java, not Mach-O
-		"checks/words/words":    []byte("\x7fELF\x02\x01\x01\x00rest"), // outside modules/ too
 	}
 	var names []string
 	for f, b := range files {
@@ -34,8 +32,8 @@ func TestFindNamesEachCompiledProgramAndNothingElse(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	if len(got) != 4 {
-		t.Fatalf("found %v; wanted modules/a/a, modules/b/cmd/b/b.exe and modules/c/c and checks/words/words only", got)
+	if len(got) != 3 {
+		t.Fatalf("found %v; wanted modules/a/a, modules/b/cmd/b/b.exe and modules/c/c only", got)
 	}
 }
 
@@ -54,36 +52,3 @@ func TestTheCatalogueHoldsNoCompiledProgram(t *testing.T) {
 		t.Errorf("%s: a compiled program is build output: remove it and add it to .gitignore (issue 1577)", f)
 	}
 }
-
-// A compiled program outside modules/ is refused too (a binary under checks/ slipped past the modules/-only rule): Files holds
-// every tracked file of a git checkout and every file of a plain folder, and Find names the binary in both.
-func TestAProgramUnderChecksIsRefused(t *testing.T) {
-	for _, git := range []bool{true, false} {
-		root := t.TempDir()
-		p := filepath.Join(root, "checks", "words", "words")
-		if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil {
-			t.Fatal(err)
-		}
-		if err := os.WriteFile(p, []byte("\x7fELF\x02\x01\x01\x00rest"), 0o644); err != nil {
-			t.Fatal(err)
-		}
-		if git {
-			for _, args := range [][]string{{"init", "-q"}, {"add", "-A"}} {
-				if out, err := exec.Command("git", append([]string{"-C", root}, args...)...).CombinedOutput(); err != nil {
-					t.Fatalf("git %v: %v: %s", args, err, out)
-				}
-			}
-		}
-		files, err := Files(root)
-		if err != nil {
-			t.Fatal(err)
-		}
-		found, err := Find(root, files)
-		if err != nil {
-			t.Fatal(err)
-		}
-		if len(found) != 1 {
-			t.Errorf("git=%v: found %v; wanted checks/words/words (ELF)", git, found)
-		}
-	}
-}

checks/nobinaries/reads-outside

@@ -1 +1,5 @@
-# every tracked file of the repository (git ls-files, no path limit): the whole tree, so this package's verdict is never kept.
+# What these tests read outside their package, as paths from the repository's root (a glob, or a directory read whole;
+# ? before a path whose absence is read). mesh-build-go hashes them into the package's digest, so its verdict is kept
+# until one of them changes (issue 1936). An empty list, or a line matching nothing, keeps nothing.
+# every file under modules/ (git ls-files and a walk).
+modules

checks/words/main.go

@@ -206,9 +206,6 @@ func excerpt(s string, from, to int) string {
 	return strings.Join(strings.Fields(s[a:b]), " ")
 }
 
-// modulePath matches a string that is only a module or import path ("git.example.org/org/repo/go/pkg").
-var modulePath = regexp.MustCompile(`^[a-z0-9.-]+\.[a-z]+/[A-Za-z0-9_./-]+$`)
-
 // goStrings returns a Go file's string literals, adjacent ones joined across `+` as the program joins them.
 func goStrings(path, rel string) ([]text, error) {
 	src, err := os.ReadFile(path)
@@ -234,11 +231,6 @@ func goStrings(path, rel string) ([]text, error) {
 			if err != nil {
 				v = lit
 			}
-			if modulePath.MatchString(v) {
-				// An import path or another module path names code, not words an agent reads.
-				cur, joining = nil, false
-				continue
-			}
 			if cur != nil && joining {
 				cur.s += v
 			} else {

modules/artifact-store-tools/cmd/artifact-store-tools/definitions.go

@@ -23,7 +23,7 @@ import (
 // manifest's.
 const NamesFileEnv = "MESH_ARTIFACT_STORE_NAMES_FILE"
 
-// CatalogueModules and CatalogueModule are the catalog's tools these definitions are read through.
+// CatalogueModules and CatalogueModule are the catalogue's tools these definitions are read through.
 const (
 	CatalogueModules = "mesh-catalog.catalog_modules"
 	CatalogueModule  = "mesh-catalog.catalog_module"
@@ -143,21 +143,21 @@ func PinsIn(manifest json.RawMessage, names StoreNames) []pinned {
 	return out
 }
 
-// Definitions is what the catalog's definitions pin in the store, and what of them could not be read.
+// Definitions is what the catalogue's definitions pin in the store, and what of them could not be read.
 type Definitions struct {
 	// Pins are by Key(repository, digest).
 	Pins map[string][]Pin
 	// Read is how many definitions were read; Unread says, per module, why its definition was not.
 	Read   int
 	Unread map[string]string
-	// NotAsked says why the catalog could not be asked at all, when it could not.
+	// NotAsked says why the catalogue could not be asked at all, when it could not.
 	NotAsked string
 	// NamesNotRead says why the store's older names could not be read, when they could not.
 	NamesNotRead string
 	Names        StoreNames
 }
 
-// Catalogue reads the definitions through the catalog's tools, and keeps each definition it read by its
+// Catalogue reads the definitions through the catalogue's tools, and keeps each definition it read by its
 // module and commit, which never change together.
 type Catalogue struct {
 	Ask Asking
@@ -171,21 +171,21 @@ type catalogueEntry struct {
 	Commit string `json:"commit"`
 }
 
-// Read asks the catalog for every module and reads each definition, bounded by DefinitionsTimeout.
+// Read asks the catalogue for every module and reads each definition, bounded by DefinitionsTimeout.
 func (c *Catalogue) Read(ctx context.Context, names StoreNames) *Definitions {
 	defs := &Definitions{Pins: map[string][]Pin{}, Unread: map[string]string{}, Names: names}
 	if c == nil || c.Ask == nil {
-		defs.NotAsked = "this bundle has no way to ask the catalog"
+		defs.NotAsked = "this bundle has no way to ask the catalogue"
 		return defs
 	}
 	raw, err := c.Ask(CatalogueModules, map[string]any{})
 	if err != nil {
-		defs.NotAsked = "the catalog's modules could not be asked: " + err.Error()
+		defs.NotAsked = "the catalogue's modules could not be asked: " + err.Error()
 		return defs
 	}
 	answer, output, ok := answerOf(raw)
 	if !ok {
-		defs.NotAsked = "the catalog refused its modules: " + lastLine(output)
+		defs.NotAsked = "the catalogue refused its modules: " + lastLine(output)
 		return defs
 	}
 	var list struct {
@@ -193,7 +193,7 @@ func (c *Catalogue) Read(ctx context.Context, names StoreNames) *Definitions {
 		Error   string           `json:"error"`
 	}
 	if err := json.Unmarshal(answer, &list); err != nil || list.Error != "" || list.Modules == nil {
-		defs.NotAsked = "the catalog's modules answer is not readable: " + firstOf(list.Error, errText(err), lastLine(output))
+		defs.NotAsked = "the catalogue's modules answer is not readable: " + firstOf(list.Error, errText(err), lastLine(output))
 		return defs
 	}
 	c.mu.Lock()

modules/artifact-store-tools/cmd/artifact-store-tools/tools.go

@@ -54,7 +54,7 @@ func Tools(s *Store, c Controller, cat *Catalogue) []stdio.Tool {
 			Name: "artifact_store_references",
 			Description: "What the controller's records say of each manifest the artifact store holds: kept (a definition " +
 				"names it, or one of the five most recent builds of a module the mesh holds), named by a definition (no " +
-				"record names it, and a definition in the catalog pins it by digest, under the store's current name or " +
+				"record names it, and a definition in the catalogue pins it by digest, under the store's current name or " +
 				"an older one: the module is said), the holder of a kept archive, " +
 				"eligible (the mesh made it and keeps it for no reason), the holder of an eligible archive, let go yet present, " +
 				"a named document the controller keeps under a tag, or unrecorded — no record names it. A platform manifest " +

modules/claude-code/cmd/claude-code/instructions.go

@@ -4,9 +4,9 @@ package main
 // the file under the agent's managed directory did not change by a byte when the module moved to Go;
 // a test holds it to that renderer's own output (testdata/rendered-by-typescript.json).
 func instructionsText(node, role string) string {
-	return "# This machine is a node of a Novox mesh\n\nWritten by the mesh's `claude-code` module. Edit the module's settings or the catalog, never this file:\nit is rewritten whenever the module renders.\n\n## Who this node is\n\n- **Node:** `" +
+	return "# This machine is a node of a Novox mesh\n\nWritten by the mesh's `claude-code` module. Edit the module's settings or the catalogue, never this file:\nit is rewritten whenever the module renders.\n\n## Who this node is\n\n- **Node:** `" +
 		node +
 		"`\n- **Role:** " +
 		role +
-		"\n- The other nodes, their roles and what runs where: ask the controller (`mesh-controller.nodes`,\n  `mesh-controller.node`). Nothing here lists them, because a copy drifts.\n\n## How a session on this mesh works\n\nThe console is the only way to the mesh: the MCP server named `mesh`. It offers five tools, and\neverything else is an address you find and call through them:\n\n- `mesh_search` — words in, matching addresses out. `mesh_describe` — one address's arguments.\n- `mesh_call` — call an address. A seat the mesh holds once is `<seat>.<verb>` (the mesh's own verbs\n  are `mesh-controller.<verb>`: `status`, `plan`, `node`, `assign`, `push`, `settings`);\n  a module on a machine is `<node>/<module>.<tool>`.\n- `mesh_overview` and `mesh_machine` — the mesh's seats and machines, and what one machine runs.\n\n- **Symptom first.** For an error, a failing service or anything unexpected, search the record with the\n  literal text before forming a hypothesis: the records module's `records_search`, then\n  `records_read`.\n- **Ask the mesh before changing it**, and change it through the controller's verbs or the catalog.\n- **A licence** through the `anthropic-licence-manager` seat's verbs. Never edit the agent's credentials\n  file by hand, never print or ask for a token.\n\n## Hard rules\n\n- A file the mesh manages is changed through the verb or the catalog that owns it, never on disk. If\n  unsure, `mesh-controller.plan` for the node says what the mesh writes there.\n- Never write to a store's database by hand; schema changes are numbered migrations.\n- Never push to a main branch: a branch, a pull request, and a human approval for every merge.\n- The mesh creates no symlinks, and nobody else does either.\n- A package is declared in a module, never installed by hand.\n\n## Conventions\n\n- Commit messages are concise, in the imperative, about why.\n- Test before pushing: nodes update unattended.\n- The playbooks in the record say how research, decisions, designs, issues and hand-offs are done.\n"
+		"\n- The other nodes, their roles and what runs where: ask the controller (`mesh-controller.nodes`,\n  `mesh-controller.node`). Nothing here lists them, because a copy drifts.\n\n## How a session on this mesh works\n\nThe console is the only way to the mesh: the MCP server named `mesh`. It offers five tools, and\neverything else is an address you find and call through them:\n\n- `mesh_search` — words in, matching addresses out. `mesh_describe` — one address's arguments.\n- `mesh_call` — call an address. A seat the mesh holds once is `<seat>.<verb>` (the mesh's own verbs\n  are `mesh-controller.<verb>`: `status`, `plan`, `node`, `assign`, `push`, `settings`);\n  a module on a machine is `<node>/<module>.<tool>`.\n- `mesh_overview` and `mesh_machine` — the mesh's seats and machines, and what one machine runs.\n\n- **Symptom first.** For an error, a failing service or anything unexpected, search the record with the\n  literal text before forming a hypothesis: the records module's `records_search`, then\n  `records_read`.\n- **Ask the mesh before changing it**, and change it through the controller's verbs or the catalogue.\n- **A licence** through the `anthropic-licence-manager` seat's verbs. Never edit the agent's credentials\n  file by hand, never print or ask for a token.\n\n## Hard rules\n\n- A file the mesh manages is changed through the verb or the catalogue that owns it, never on disk. If\n  unsure, `mesh-controller.plan` for the node says what the mesh writes there.\n- Never write to a store's database by hand; schema changes are numbered migrations.\n- Never push to a main branch: a branch, a pull request, and a human approval for every merge.\n- The mesh creates no symlinks, and nobody else does either.\n- A package is declared in a module, never installed by hand.\n\n## Conventions\n\n- Commit messages are concise, in the imperative, about why.\n- Test before pushing: nodes update unattended.\n- The playbooks in the record say how research, decisions, designs, issues and hand-offs are done.\n"
 }

modules/claude-code/cmd/claude-code/testdata/rendered-by-typescript.json

@@ -32,11 +32,11 @@
   "withKey": {
     "managed-mcp.json": "{\n  \"mcpServers\": {\n    \"anton\": {\n      \"type\": \"stdio\",\n      \"command\": \"node\",\n      \"args\": [\n        \"/a/b.js\"\n      ],\n      \"env\": {}\n    },\n    \"docs\": {\n      \"type\": \"stdio\",\n      \"command\": \"docs-mcp\",\n      \"args\": [\n        \"--x\"\n      ]\n    },\n    \"mesh\": {\n      \"type\": \"http\",\n      \"url\": \"http://127.0.0.1:4270/mcp\"\n    },\n    \"search\": {\n      \"type\": \"http\",\n      \"url\": \"https://s.example/mcp\"\n    }\n  }\n}\n",
     "managed-settings.json": "{\n  \"attribution\": {\n    \"commit\": \"\",\n    \"pr\": \"\"\n  },\n  \"allowAllClaudeAiMcps\": true,\n  \"apiKeyHelper\": \"/state/api-key-helper\"\n}\n",
-    "CLAUDE.md": "# This machine is a node of a Novox mesh\n\nWritten by the mesh's `claude-code` module. Edit the module's settings or the catalog, never this file:\nit is rewritten whenever the module renders.\n\n## Who this node is\n\n- **Node:** `workstation`\n- **Role:** the laptop\n- The other nodes, their roles and what runs where: ask the controller (`mesh-controller.nodes`,\n  `mesh-controller.node`). Nothing here lists them, because a copy drifts.\n\n## How a session on this mesh works\n\nThe console is the only way to the mesh: the MCP server named `mesh`. It offers five tools, and\neverything else is an address you find and call through them:\n\n- `mesh_search` — words in, matching addresses out. `mesh_describe` — one address's arguments.\n- `mesh_call` — call an address. A seat the mesh holds once is `<seat>.<verb>` (the mesh's own verbs\n  are `mesh-controller.<verb>`: `status`, `plan`, `node`, `assign`, `push`, `settings`);\n  a module on a machine is `<node>/<module>.<tool>`.\n- `mesh_overview` and `mesh_machine` — the mesh's seats and machines, and what one machine runs.\n\n- **Symptom first.** For an error, a failing service or anything unexpected, search the record with the\n  literal text before forming a hypothesis: the records module's `records_search`, then\n  `records_read`.\n- **Ask the mesh before changing it**, and change it through the controller's verbs or the catalog.\n- **A licence** through the `anthropic-licence-manager` seat's verbs. Never edit the agent's credentials\n  file by hand, never print or ask for a token.\n\n## Hard rules\n\n- A file the mesh manages is changed through the verb or the catalog that owns it, never on disk. If\n  unsure, `mesh-controller.plan` for the node says what the mesh writes there.\n- Never write to a store's database by hand; schema changes are numbered migrations.\n- Never push to a main branch: a branch, a pull request, and a human approval for every merge.\n- The mesh creates no symlinks, and nobody else does either.\n- A package is declared in a module, never installed by hand.\n\n## Conventions\n\n- Commit messages are concise, in the imperative, about why.\n- Test before pushing: nodes update unattended.\n- The playbooks in the record say how research, decisions, designs, issues and hand-offs are done.\n"
+    "CLAUDE.md": "# This machine is a node of a Novox mesh\n\nWritten by the mesh's `claude-code` module. Edit the module's settings or the catalogue, never this file:\nit is rewritten whenever the module renders.\n\n## Who this node is\n\n- **Node:** `workstation`\n- **Role:** the laptop\n- The other nodes, their roles and what runs where: ask the controller (`mesh-controller.nodes`,\n  `mesh-controller.node`). Nothing here lists them, because a copy drifts.\n\n## How a session on this mesh works\n\nThe console is the only way to the mesh: the MCP server named `mesh`. It offers five tools, and\neverything else is an address you find and call through them:\n\n- `mesh_search` — words in, matching addresses out. `mesh_describe` — one address's arguments.\n- `mesh_call` — call an address. A seat the mesh holds once is `<seat>.<verb>` (the mesh's own verbs\n  are `mesh-controller.<verb>`: `status`, `plan`, `node`, `assign`, `push`, `settings`);\n  a module on a machine is `<node>/<module>.<tool>`.\n- `mesh_overview` and `mesh_machine` — the mesh's seats and machines, and what one machine runs.\n\n- **Symptom first.** For an error, a failing service or anything unexpected, search the record with the\n  literal text before forming a hypothesis: the records module's `records_search`, then\n  `records_read`.\n- **Ask the mesh before changing it**, and change it through the controller's verbs or the catalogue.\n- **A licence** through the `anthropic-licence-manager` seat's verbs. Never edit the agent's credentials\n  file by hand, never print or ask for a token.\n\n## Hard rules\n\n- A file the mesh manages is changed through the verb or the catalogue that owns it, never on disk. If\n  unsure, `mesh-controller.plan` for the node says what the mesh writes there.\n- Never write to a store's database by hand; schema changes are numbered migrations.\n- Never push to a main branch: a branch, a pull request, and a human approval for every merge.\n- The mesh creates no symlinks, and nobody else does either.\n- A package is declared in a module, never installed by hand.\n\n## Conventions\n\n- Commit messages are concise, in the imperative, about why.\n- Test before pushing: nodes update unattended.\n- The playbooks in the record say how research, decisions, designs, issues and hand-offs are done.\n"
   },
   "plain": {
     "managed-mcp.json": "{\n  \"mcpServers\": {\n    \"mesh\": {\n      \"type\": \"http\",\n      \"url\": \"http://127.0.0.1:4270/mcp\"\n    }\n  }\n}\n",
     "managed-settings.json": "{\n  \"attribution\": {\n    \"commit\": \"\",\n    \"pr\": \"\"\n  },\n  \"allowAllClaudeAiMcps\": true\n}\n",
-    "CLAUDE.md": "# This machine is a node of a Novox mesh\n\nWritten by the mesh's `claude-code` module. Edit the module's settings or the catalog, never this file:\nit is rewritten whenever the module renders.\n\n## Who this node is\n\n- **Node:** `workstation`\n- **Role:** not stated — set it in this module's settings for the node\n- The other nodes, their roles and what runs where: ask the controller (`mesh-controller.nodes`,\n  `mesh-controller.node`). Nothing here lists them, because a copy drifts.\n\n## How a session on this mesh works\n\nThe console is the only way to the mesh: the MCP server named `mesh`. It offers five tools, and\neverything else is an address you find and call through them:\n\n- `mesh_search` — words in, matching addresses out. `mesh_describe` — one address's arguments.\n- `mesh_call` — call an address. A seat the mesh holds once is `<seat>.<verb>` (the mesh's own verbs\n  are `mesh-controller.<verb>`: `status`, `plan`, `node`, `assign`, `push`, `settings`);\n  a module on a machine is `<node>/<module>.<tool>`.\n- `mesh_overview` and `mesh_machine` — the mesh's seats and machines, and what one machine runs.\n\n- **Symptom first.** For an error, a failing service or anything unexpected, search the record with the\n  literal text before forming a hypothesis: the records module's `records_search`, then\n  `records_read`.\n- **Ask the mesh before changing it**, and change it through the controller's verbs or the catalog.\n- **A licence** through the `anthropic-licence-manager` seat's verbs. Never edit the agent's credentials\n  file by hand, never print or ask for a token.\n\n## Hard rules\n\n- A file the mesh manages is changed through the verb or the catalog that owns it, never on disk. If\n  unsure, `mesh-controller.plan` for the node says what the mesh writes there.\n- Never write to a store's database by hand; schema changes are numbered migrations.\n- Never push to a main branch: a branch, a pull request, and a human approval for every merge.\n- The mesh creates no symlinks, and nobody else does either.\n- A package is declared in a module, never installed by hand.\n\n## Conventions\n\n- Commit messages are concise, in the imperative, about why.\n- Test before pushing: nodes update unattended.\n- The playbooks in the record say how research, decisions, designs, issues and hand-offs are done.\n"
+    "CLAUDE.md": "# This machine is a node of a Novox mesh\n\nWritten by the mesh's `claude-code` module. Edit the module's settings or the catalogue, never this file:\nit is rewritten whenever the module renders.\n\n## Who this node is\n\n- **Node:** `workstation`\n- **Role:** not stated — set it in this module's settings for the node\n- The other nodes, their roles and what runs where: ask the controller (`mesh-controller.nodes`,\n  `mesh-controller.node`). Nothing here lists them, because a copy drifts.\n\n## How a session on this mesh works\n\nThe console is the only way to the mesh: the MCP server named `mesh`. It offers five tools, and\neverything else is an address you find and call through them:\n\n- `mesh_search` — words in, matching addresses out. `mesh_describe` — one address's arguments.\n- `mesh_call` — call an address. A seat the mesh holds once is `<seat>.<verb>` (the mesh's own verbs\n  are `mesh-controller.<verb>`: `status`, `plan`, `node`, `assign`, `push`, `settings`);\n  a module on a machine is `<node>/<module>.<tool>`.\n- `mesh_overview` and `mesh_machine` — the mesh's seats and machines, and what one machine runs.\n\n- **Symptom first.** For an error, a failing service or anything unexpected, search the record with the\n  literal text before forming a hypothesis: the records module's `records_search`, then\n  `records_read`.\n- **Ask the mesh before changing it**, and change it through the controller's verbs or the catalogue.\n- **A licence** through the `anthropic-licence-manager` seat's verbs. Never edit the agent's credentials\n  file by hand, never print or ask for a token.\n\n## Hard rules\n\n- A file the mesh manages is changed through the verb or the catalogue that owns it, never on disk. If\n  unsure, `mesh-controller.plan` for the node says what the mesh writes there.\n- Never write to a store's database by hand; schema changes are numbered migrations.\n- Never push to a main branch: a branch, a pull request, and a human approval for every merge.\n- The mesh creates no symlinks, and nobody else does either.\n- A package is declared in a module, never installed by hand.\n\n## Conventions\n\n- Commit messages are concise, in the imperative, about why.\n- Test before pushing: nodes update unattended.\n- The playbooks in the record say how research, decisions, designs, issues and hand-offs are done.\n"
   }
 }

modules/gitea/index.ts

@@ -53,9 +53,8 @@ import { announce, keepWatermark, readWatermark } from "./announce.js";
 import { mergeTool } from "./merge.js";
 import { GiteaAdmin, GiteaClient, movedSince } from "./client.js";
 import { keepMainRules, mainRulesStep } from "./mainrules.js";
-import { CHECK_CONTEXT, CHECK_STATUS, REPO_CHECK_CONTEXT, commentFor, composedGate, groupGateStatus, headKey, maintained,
-  requiredOf, statusesFor, writesGate, type Announced, type Checked, repoCheckFacts } from "./pulls.js";
-import { actOn, announceNewHeads, startPass } from "./watch.js";
+import { CHECK_CONTEXT, CHECK_STATUS, REPO_CHECK_CONTEXT, commentFor, composedGate, groupGateStatus, headKey, headsToAnnounce, maintained,
+  requiredOf, statusesFor, writesGate, type Announced, type Checked, repoCheckFacts, reposToLook } from "./pulls.js";
 import { GateWriter } from "./gate.js";
 import { HOOK_PATH, HOOK_PORT, Pace, claimHead, ensureSystemHook, eventsTool, keptSecret, receiver, type ForgeEvent } from "./webhook.js";
 import { keepSiblings, noteComposed, noteVerdict, readSiblings, siblingsFile, siblingsOf, weighSiblings } from "./siblings.js";
@@ -139,7 +138,12 @@ async function pollMerged(client: GiteaClient): Promise<void> {
       // Closed unmerged (novox/hq ADR 0239): announced once, since the watching began, so its delivery stops.
       const closedKey = `closed:${repo.full_name}#${pull.number}`;
       if (!pull.merged && pull.state === "closed" && !announced.has(closedKey)) {
-        if (primedMerges && !!pull.updated_at && !!since && pull.updated_at > since) await announceClosed(client, repo, pull);
+        if (primedMerges && !!pull.updated_at && !!since && pull.updated_at > since) {
+          await announce("pull.closed", { owner: repo.owner, repo: repo.name, number: pull.number, title: pull.title,
+            head: pull.head, head_sha: pull.head_sha, base: pull.base, html_url: pull.html_url });
+          console.log(`[gitea] announced ${repo.full_name}#${pull.number} closed unmerged`);
+          await siblingMoves(client, repo.full_name, pull.number);
+        }
         announced.add(closedKey);
         continue;
       }
@@ -164,23 +168,6 @@ async function pollMerged(client: GiteaClient): Promise<void> {
 type RepoOf = { owner: string; name: string; full_name: string; clone_url?: string };
 type PullOf = Awaited<ReturnType<GiteaClient["listPullRequests"]>>[number];
 
-/** A pull request closed without a merge, announced once (ADR 0239): by its event, or by the start's pass. */
-async function announceClosed(client: GiteaClient, repo: RepoOf, pull: PullOf): Promise<boolean> {
-  const closedKey = `closed:${repo.full_name}#${pull.number}`;
-  if (pull.merged || pull.state !== "closed" || announced.has(closedKey)) return false;
-  announced.add(closedKey);
-  try {
-    await announce("pull.closed", { owner: repo.owner, repo: repo.name, number: pull.number, title: pull.title,
-      head: pull.head, head_sha: pull.head_sha, base: pull.base, html_url: pull.html_url });
-  } catch (err) {
-    announced.delete(closedKey);
-    throw err;
-  }
-  console.log(`[gitea] announced ${repo.full_name}#${pull.number} closed unmerged`);
-  await siblingMoves(client, repo.full_name, pull.number);
-  return true;
-}
-
 /** **A merge, announced once, whichever path saw it first** (novox/hq issue 729): the poll or the forge's event. */
 async function announceMerge(client: GiteaClient, repo: RepoOf, pull: PullOf): Promise<boolean> {
   if (!pull.merged || !pull.merge_commit_sha || announced.has(pull.merge_commit_sha)) return false;
@@ -294,18 +281,43 @@ async function alreadyChecked(client: GiteaClient, repo: RepoOf, pull: OpenOf):
 }
 
 let lastPullLook = "";
-/** The pass over every open pull request: run at the start and when the receiver listens, never on a timer (issue 1422). */
-async function passPulls(client: GiteaClient): Promise<void> {
+// **A sweep now and then looks at every repository** (novox/hq issue 347), whatever moved: the floor is a
+// heuristic, and a heuristic that misses is caught by the next sweep rather than never.
+const SWEEP_MS = 10 * 60_000;
+let lastSweep = 0;
+async function pollPulls(client: GiteaClient): Promise<void> {
   const began = new Date().toISOString();
+  const floor = lastPullLook ? new Date(Date.parse(lastPullLook) - MARGIN_MS).toISOString() : "";
   const dayAgo = new Date(Date.now() - 24 * 3600_000).toISOString();
-  for (const repo of await client.listAllRepos()) {
-    // Every open pull request, paged (novox/hq issue 579).
-    const open = await client.listOpenPullsSince(repo.owner, repo.name, "");
-    await announceNewHeads(repo.full_name, open, heads, primedPulls, dayAgo, {
-      alreadyChecked: (pull) => alreadyChecked(client, repo, pull),
-      announceHead: (pull) => announceHead(client, repo, pull),
-      missed: (what) => pace.miss(what),
-    });
+  // A pull request opened, reopened or retargeted moves its own update time and not its repository's: the
+  // pull requests updated since the floor are found by their own (issue 347). A search that fails is a sweep.
+  let sweep = Date.now() - lastSweep >= SWEEP_MS;
+  let updated: { owner: string; name: string; updated_at?: string }[] = [];
+  if (floor && !sweep) {
+    try {
+      updated = await client.searchOpenPulls(floor);
+    } catch (err) {
+      console.error(`[gitea] the pull requests updated lately could not be searched, so every repository is looked at — ${err instanceof Error ? err.message : err}`);
+      sweep = true;
+    }
+  }
+  if (sweep) lastSweep = Date.now();
+  for (const repo of reposToLook(await client.listAllRepos(), floor, updated, sweep)) {
+    // Every open pull request updated since the floor, paged (novox/hq issue 579): the newest 20 alone left a head
+    // beyond them unannounced. A sweep and the first pass read every page.
+    const open = await client.listOpenPullsSince(repo.owner, repo.name, sweep ? "" : floor);
+    for (const pull of headsToAnnounce(repo.full_name, open, heads)) {
+      const key = headKey(repo.full_name, pull.number, pull.base);
+      const fresh = primedPulls || (!!pull.updated_at && pull.updated_at > dayAgo);
+      // The first look after a start remembers nothing: a head the forge already shows a merge check of was announced.
+      if (fresh && !primedPulls && await alreadyChecked(client, repo, pull)) {
+        heads[key] = String(pull.head_sha);
+        continue;
+      }
+      if (fresh) {
+        if (await announceHead(client, repo, pull)) pace.miss(`${key} at ${String(pull.head_sha).slice(0, 8)}`);
+      } else heads[key] = String(pull.head_sha);
+    }
     if (await trunksMoved(client, repo.owner, repo.name)) changedTrunks = true;
   }
   if (changedTrunks) keepTrunks();
@@ -485,9 +497,6 @@ const checks = new CheckStatuses({
 /** How fast the polls look: 30 s until the forge's events are heard, five minutes while they are; and what
  *  gitea_events says of them (webhook.ts). */
 const pace = new Pace();
-/** Asks the pass over every repository again, shortly and once (set where the pass is made): an event that could not be
- *  acted on is not lost until the next start. */
-let catchUp: () => void = () => {};
 if (!gitea) pace.unheard("the forge is not watched: no way to a token", false);
 
 // The states this module keeps and which others may read, said on the bus before it serves (novox/hq ADR 0495 clause 2).
@@ -513,15 +522,22 @@ registerModuleTools("gitea", () => [eventsTool(pace), ...readAllTools(readAll),
   gates,
 }), mergeTool(gitea, { gates })] : [])]);
 
-/** What the forge's event asks of the announcer at once (issue 729, 1422): see watch.ts. */
-const actOnEvent = (client: GiteaClient, event: ForgeEvent): Promise<void> => actOn<RepoOf, PullOf>(event, {
-  getRepo: (o, r) => client.getRepo(o, r),
-  getPull: (o, r, n) => client.getPullRequest(o, r, n) as Promise<PullOf & { state?: string; merged?: boolean }>,
-  announceHead: (repo, pull) => announceHead(client, repo, pull as OpenOf),
-  announceMerge: (repo, pull) => announceMerge(client, repo, pull),
-  announceClosed: (repo, pull) => announceClosed(client, repo, pull),
-  siblingMoves: (full, n) => siblingMoves(client, full, n),
-});
+/** What the forge's event asks of the announcer at once (issue 729): a new head is announced, and a merge. */
+async function actOn(client: GiteaClient, event: ForgeEvent): Promise<void> {
+  const b = event.body as { owner?: string; repo?: string; number?: number };
+  if (!b.owner || !b.repo || !b.number) return;
+  if (event.name === "forge.pull-request.closed") {
+    // Closed unmerged is a sibling's move; a merge is weighed with its announcement below (ADR 0382 §5).
+    if (!(event.body as { merged?: boolean }).merged) await siblingMoves(client, `${b.owner}/${b.repo}`, b.number);
+    return;
+  }
+  const head = ["forge.pull-request.opened", "forge.pull-request.synchronized", "forge.pull-request.reopened"].includes(event.name);
+  const merged = event.name === "forge.pull-request.merged";
+  if (!head && !merged) return;
+  const [repo, pull] = await Promise.all([client.getRepo(b.owner, b.repo), client.getPullRequest(b.owner, b.repo, b.number)]);
+  if (head && pull.state === "open") await announceHead(client, repo, pull);
+  if (merged) await announceMerge(client, repo, pull);
+}
 
 /**
  * **The receiver, and the forge's one system webhook pointing at it** (issue 729). The secret is minted and kept beside
@@ -547,12 +563,7 @@ async function listenForForge(client: GiteaClient): Promise<boolean> {
         // A repository made, or one not yet seen readable, is granted read before anything acts on it (readall.ts).
         await Promise.resolve().then(() => readAll().onEvent(event)).catch((err) =>
           console.error(`[gitea] whether the mesh's accounts read the repository of ${event.name} could not be settled — ${err instanceof Error ? err.message : err}`));
-        try {
-          await actOnEvent(client, event);
-        } catch (err) {
-          catchUp();
-          throw err;
-        }
+        await actOn(client, event);
       } });
     await new Promise<void>((resolve, reject) => {
       server.once("error", reject);
@@ -601,9 +612,9 @@ if (gitea) {
   // polls slow to every five minutes and announce only what no event said (Pace); otherwise they keep 30 s.
   // **Not awaited** (novox/hq issue 1726): the receiver's set-up asks the forge's admin API, and the runtime kills a bundle
   // whose import has not ended in its 10 s handshake and never starts it again; a forge slow to answer while every bundle
-  // of the node starts left gitea_commit_status, gitea_merge_pull_request and gitea_events served nowhere. The pass below
-  // runs again once it is listening, so nothing said before is missed; listenForForge says its own failure.
-  const listenOk = listenForForge(client);
+  // of the node starts left gitea_commit_status, gitea_merge_pull_request and gitea_events served nowhere. Until it is
+  // listening, Pace keeps the polls at 30 s, so nothing is missed meanwhile; listenForForge says its own failure.
+  void listenForForge(client);
   // The start's one pass over every repository (readall.ts), not awaited for the same reason. A forge not answering yet
   // is asked again, a minute apart, until one pass has run; after that only the forge's events grant.
   // An account of the list the forge does not hold yet (the forge-account provider makes nox-builder and nox-agent when
@@ -635,20 +646,8 @@ if (gitea) {
   // Only while the setting keep-main-rules is true (mainrules.ts); false, the default, leaves every repository's rule as set.
   tick(mainRulesStep(keepMainRules(), () => GiteaAdmin.fromEnv().ensureMainMerges("novox"), (line) => console.log(line)), 600_000);
   tick(() => pollRepos(client), 60_000);
-  // **No timer asks the forge for pull requests or merges** (issue 1422): the forge's events announce them. One pass over
-  // every repository runs at the start and again once the receiver listens, so what happened while the module was away or
-  // not yet listening is announced; passes run one at a time, a failed one is asked again a minute later.
-  let passes: Promise<void> = Promise.resolve();
-  const pass = (): Promise<void> => (passes = passes.catch(() => {}).then(() =>
-    startPass(async () => { await pollMerged(client); await passPulls(client); }, { retryMs: 60_000 })));
-  void pass();
-  let catchUpAsked = false;
-  catchUp = () => {
-    if (catchUpAsked) return;
-    catchUpAsked = true;
-    setTimeout(() => { catchUpAsked = false; void pass(); }, 30_000);
-  };
-  void listenOk.then((ok) => (ok ? pass() : undefined));
+  tick(() => pollMerged(client), () => pace.every());
+  tick(() => pollPulls(client), () => pace.every());
   // Bound again until they hold, and not awaited (bind.ts, issue 1793): the runtime kills a bundle that has not answered its
   // handshake in 10 s, so the import must end while a refused bind is still asked again.
   bindInBackground([

modules/gitea/test/watch.test.ts

@@ -1,73 +0,0 @@
-import assert from "node:assert/strict";
-import { mock, test } from "node:test";
-import type { GiteaPull } from "../client.ts";
-
-// **No poll of the forge** (issue 1422, notes 10 and 11): the forge's events announce heads and merges; a pass runs once at
-// the start and when the receiver listens.
-
-const edited = (base: string) => ({ name: "forge.pull-request.edited", body: { owner: "novox", repo: "hq", number: 7, base, merged: false } });
-
-function deps() {
-  const calls: string[] = [];
-  return { calls, d: {
-    getRepo: async () => ({ r: 1 }),
-    getPull: async () => ({ state: "open", base: "trunk" }) as any,
-    announceHead: async () => { calls.push("head"); },
-    announceMerge: async () => { calls.push("merge"); },
-    announceClosed: async () => { calls.push("closed"); },
-    siblingMoves: async () => { calls.push("siblings"); },
-  } };
-}
-
-test("an edited event announces the head into the base it now has, without a poll", async () => {
-  const { actOn } = await import("../watch.ts");
-  const { calls, d } = deps();
-  await actOn(edited("trunk"), d);
-  assert.deepEqual(calls, ["head"]);
-});
-
-test("a close without a merge is announced by its event, a merged close is left to the merge event", async () => {
-  const { actOn } = await import("../watch.ts");
-  const { calls, d } = deps();
-  await actOn({ name: "forge.pull-request.closed", body: { owner: "novox", repo: "hq", number: 7, merged: false } }, d);
-  assert.deepEqual(calls, ["closed", "siblings"]);
-  calls.length = 0;
-  await actOn({ name: "forge.pull-request.closed", body: { owner: "novox", repo: "hq", number: 7, merged: true } }, d);
-  assert.deepEqual(calls, []);
-});
-
-test("no timer polls after the start: one pass ends and nothing is scheduled; a failed one is asked again", async () => {
-  const { startPass } = await import("../watch.ts");
-  mock.timers.enable({ apis: ["setTimeout", "setInterval"] });
-  try {
-    let runs = 0;
-    await startPass(async () => { runs++; }, { retryMs: 60_000, log: () => {} });
-    mock.timers.tick(24 * 3600_000);
-    assert.equal(runs, 1, "a day later the forge was not asked again");
-    let tries = 0;
-    const retried = startPass(async () => { if (++tries < 2) throw new Error("forge down"); }, { retryMs: 60_000, log: () => {} });
-    await Promise.resolve(); await Promise.resolve();
-    mock.timers.tick(60_000);
-    await retried;
-    assert.equal(tries, 2);
-  } finally {
-    mock.timers.reset();
-  }
-});
-
-test("a start pass announces a head nobody announced, and only remembers one the forge shows a check of", async () => {
-  const { announceNewHeads } = await import("../watch.ts");
-  const pull = (n: number, sha: string): GiteaPull => ({ number: n, state: "open", head_sha: sha, base: "main",
-    updated_at: new Date().toISOString() } as unknown as GiteaPull);
-  const announced: number[] = [], said: string[] = [];
-  const heads: Record<string, string> = {};
-  await announceNewHeads("novox/hq", [pull(1, "a".repeat(40)), pull(2, "b".repeat(40))], heads, false,
-    new Date(Date.now() - 24 * 3600_000).toISOString(), {
-      alreadyChecked: async (p) => p.number === 2,
-      announceHead: async (p) => { announced.push(p.number); return true; },
-      missed: (w) => said.push(w),
-    });
-  assert.deepEqual(announced, [1]);
-  assert.equal(heads["novox/hq#2@main"], "b".repeat(40), "the checked head is remembered, not announced");
-  assert.equal(said.length, 1);
-});

modules/gitea/test/webhook.test.ts

@@ -251,8 +251,7 @@ test("a forge that never delivers is said loudly once, and unhealthy, when the p
   assert.equal(r.healthy, true);
   assert.equal(r.verified.count, 1);
   assert.equal(r.verified.last.event, "push");
-  assert.equal(r.polls.every_seconds, null);
-  assert.equal(r.polls.hearing, true);
+  assert.equal(r.polls.every_seconds, 300);
   assert.match(said.join("\n"), /heard again/);
 });
 
@@ -315,19 +314,24 @@ test("without a receiver by configuration the polls alone watch, healthy; a rece
   assert.match(r.why, /403/);
 });
 
-test("nothing is paced: the report says no timer asks the forge, and a miss is still counted and said", async () => {
+test("the polls look every 30 s until events are heard, every five minutes while they are, and 30 s again on a miss", async () => {
   const { Pace } = await import("../webhook.ts");
   let now = 1_000_000;
   const said: string[] = [];
   const pace = new Pace(() => now, (l) => said.push(l));
-  assert.equal((pace as any).every, undefined, "no pace to ask");
-  assert.equal((pace.report() as any).polls.every_seconds, null);
+  assert.equal(pace.every(), 30_000, "no delivery yet");
+  pace.heard();
+  assert.equal(pace.every(), 300_000, "a delivery heard");
+  now += 11 * 60_000;
+  assert.equal(pace.every(), 30_000, "ten minutes without a delivery");
   pace.heard();
-  assert.equal((pace.report() as any).polls.hearing, true);
   now += 1000;
   pace.miss("novox/hq#7 at aaaaaaaa");
-  assert.equal((pace.report() as any).polls.hearing, false, "the pass found what no event said");
+  assert.equal(pace.every(), 30_000, "the poll found what no event said");
   assert.match(said.join("\n"), /MISSED novox\/hq#7/);
+  now += 1000;
+  pace.heard();
+  assert.equal(pace.every(), 300_000, "the next delivery");
 });
 
 // Issue 1079: a pull request's edit event carries its description, so mesh-delivery reads a Reviewed-by line written after

modules/gitea/tools/index.ts

@@ -637,7 +637,7 @@ function allGiteaTools(gitea: GiteaClient, admin?: () => GiteaAdmin): ToolDefini
     },
     {
       name: "gitea_commit_trees",
-      description: "A commit's trees from the forge's one recursive listing: the root tree, and the tree of every directory that holds a module.json (the root as an empty name), each by its git hash. What the forge bridge puts in a merge's message (novox/hq ADR 0437 §5). With paths, {directory: [path relative to it]}, the answer also carries paths, {directory: {path: git object id}} of each named file or directory at the commit (novox/hq ADR 0499 §3); a path the commit lacks fails naming the directory and the path. The commit is a full 40-hex sha. With listed, [directory], the answer also carries listed, {directory: {name: git blob id}} of the files directly under each (the catalog's placement files, novox/hq ADR 0549 §2). A listing the forge cut is refused, never answered in part. Reads only.",
+      description: "A commit's trees from the forge's one recursive listing: the root tree, and the tree of every directory that holds a module.json (the root as an empty name), each by its git hash. What the forge bridge puts in a merge's message (novox/hq ADR 0437 §5). With paths, {directory: [path relative to it]}, the answer also carries paths, {directory: {path: git object id}} of each named file or directory at the commit (novox/hq ADR 0499 §3); a path the commit lacks fails naming the directory and the path. The commit is a full 40-hex sha. With listed, [directory], the answer also carries listed, {directory: {name: git blob id}} of the files directly under each (the catalogue's placement files, novox/hq ADR 0549 §2). A listing the forge cut is refused, never answered in part. Reads only.",
       input: {
         owner: { type: "string", description: "the repository owner" },
         repo: { type: "string", description: "the repository name" },

modules/gitea/watch.ts

@@ -1,87 +0,0 @@
-// What the forge's events ask of the announcer, and the one pass at a start (issue 1422, notes 10 and 11). Nothing polls the
-// forge: a head or merge is announced when its event is heard, and a pass over every repository runs once when the module
-// starts and again when the receiver is listening, so what happened while it was down is announced too.
-//
-// Apart from index.ts, which has side effects at import, so these are tested with the announcers injected.
-
-import type { GiteaPull, GiteaRepo } from "./client.js";
-import type { Announced } from "./pulls.js";
-import { headKey, headsToAnnounce } from "./pulls.js";
-import type { ForgeEvent } from "./webhook.js";
-
-export interface ActDeps<R, P> {
-  getRepo(owner: string, repo: string): Promise<R>;
-  getPull(owner: string, repo: string, number: number): Promise<P & { state?: string; merged?: boolean }>;
-  announceHead(repo: R, pull: P): Promise<unknown>;
-  announceMerge(repo: R, pull: P): Promise<unknown>;
-  announceClosed(repo: R, pull: P): Promise<unknown>;
-  siblingMoves(full: string, number: number): Promise<unknown>;
-}
-
-const HEAD_EVENTS = ["forge.pull-request.opened", "forge.pull-request.synchronized", "forge.pull-request.reopened"];
-
-/**
- * What the forge's event asks of the announcer at once: a new head is announced, a merge, a close without a merge, and a
- * pull request retargeted (an edit: the head is announced into the base it now has — the base is in the head's key, so an
- * edit that changed nothing about the base announces nothing).
- */
-export async function actOn<R, P>(event: ForgeEvent, d: ActDeps<R, P>): Promise<void> {
-  const b = event.body as { owner?: string; repo?: string; number?: number; merged?: boolean };
-  if (!b.owner || !b.repo || !b.number) return;
-  const edited = event.name === "forge.pull-request.edited";
-  const closed = event.name === "forge.pull-request.closed";
-  const head = HEAD_EVENTS.includes(event.name) || edited;
-  const merged = event.name === "forge.pull-request.merged";
-  if (!head && !merged && !closed) return;
-  if (closed && b.merged) return; // a merge is weighed with its own event (ADR 0382 §5)
-  const [repo, pull] = await Promise.all([d.getRepo(b.owner, b.repo), d.getPull(b.owner, b.repo, b.number)]);
-  if (closed) {
-    await d.announceClosed(repo, pull);
-    await d.siblingMoves(`${b.owner}/${b.repo}`, b.number);
-    return;
-  }
-  if (head && pull.state === "open") await d.announceHead(repo, pull);
-  if (merged) await d.announceMerge(repo, pull);
-}
-
-/**
- * The one pass at a start, and its retry: run now; if it fails, say so and run again after `retryMs`, until one pass has
- * ended. A retry of a failed pass, never a poll: after a pass has ended nothing is scheduled.
- */
-export function startPass(run: () => Promise<void>, opts: { retryMs: number; log?: (l: string) => void }): Promise<void> {
-  const log = opts.log ?? ((l) => console.error(`[gitea] ${l}`));
-  return run().catch((err) => {
-    log(`the pass over every repository failed, asked again in ${opts.retryMs / 1000} s — ${err instanceof Error ? err.message : err}`);
-    return new Promise<void>((resolve) => setTimeout(() => resolve(startPass(run, opts)), opts.retryMs));
-  });
-}
-
-export interface HeadDeps {
-  /** Whether the forge shows a merge check of the head: only an announced head has one. */
-  alreadyChecked(pull: GiteaPull): Promise<boolean>;
-  /** Announce it; true when it was this call that announced it (not an event before it). */
-  announceHead(pull: GiteaPull): Promise<boolean>;
-  /** Told of a head this pass announced that no event had. */
-  missed(what: string): void;
-}
-
-/**
- * The heads of one repository's open pull requests a pass announces. A head is announced when it is new and fresh (moved in
- * the last day); at the first pass after a start (`primed` false) one the forge shows a merge check of was announced
- * already, and is only remembered.
- */
-export async function announceNewHeads(full: string, open: GiteaPull[], heads: Announced, primed: boolean, dayAgo: string, d: HeadDeps): Promise<void> {
-  for (const pull of headsToAnnounce(full, open, heads)) {
-    const key = headKey(full, pull.number, pull.base);
-    const fresh = primed || (!!pull.updated_at && pull.updated_at > dayAgo);
-    if (fresh && !primed && await d.alreadyChecked(pull)) {
-      heads[key] = String(pull.head_sha);
-      continue;
-    }
-    if (fresh) {
-      if (await d.announceHead(pull)) d.missed(`${key} at ${String(pull.head_sha).slice(0, 8)}`);
-    } else heads[key] = String(pull.head_sha);
-  }
-}
-
-export type { GiteaRepo };

modules/gitea/webhook.ts

@@ -3,7 +3,7 @@
 // with a secret it mints and keeps beside its token; the receiver refuses whatever is unsigned or does not verify, and
 // publishes each event, trimmed, on the module's events as forge.<kind>.<action> (forge.pull-request.opened, forge.push, …),
 // on the shared EVENTS path its other events take; its own stream (ADR 0363) is a follow-up once issue 725 ships.
-// No poll is the safety net (issue 1422); the announced-heads and announced-merges records keep anything from
+// The polls stay as the safety net, slowed; the announced-heads and announced-merges records keep anything from
 // being announced twice, whichever path saw it first.
 //
 // The secret is never logged: lines say it was minted or reused and where it is kept, never what it is.
@@ -144,7 +144,7 @@ export interface ReceiverOptions {
   publish: (event: ForgeEvent) => Promise<void>;
   /** Acts on it at once, beside publishing it (the announcer). */
   act?: (event: ForgeEvent) => Promise<void>;
-  /** Told of every verified delivery — its kind (X-Gitea-Event) and its delivery id — so the module knows events are
+  /** Told of every verified delivery — its kind (X-Gitea-Event) and its delivery id — so the polls know events are
    *  heard, and the module can say when it last heard one. */
   heard?: (kind: string, delivery: string) => void;
   /** Told of every refused delivery, with the reason and where it came from. */
@@ -242,7 +242,7 @@ export function receiver(opts: ReceiverOptions): Server & { idle(): Promise<void
           await opts.publish(event);
           if (opts.act) await opts.act(event);
         } catch (err) {
-          log(`a forge event ${event.name} could not be published or acted on; the pass over every repository is asked again shortly — ${err instanceof Error ? err.message : err}`);
+          log(`a forge event ${event.name} could not be published or acted on; the polls catch it — ${err instanceof Error ? err.message : err}`);
         }
       });
     });
@@ -276,13 +276,14 @@ export interface HookState {
 export const SILENT_AFTER = 10 * 60_000;
 
 /**
- * **Whether the forge's events are heard** (issues 729, 1422). Nothing polls the forge, so there is no pace: a delivery
- * heard within the last ten minutes, and none missed since, is `hearing`.
+ * **How fast the polls look, and whether the forge's events are heard** (issue 729): every five minutes only while the
+ * forge's events are heard — a verified delivery within the last ten minutes, and none missed since. Until the first
+ * delivery, after ten minutes without one, or once the poll found something no event said, every thirty seconds.
  *
  * It also keeps what `gitea_events` says: where the receiver listens, the hook as ensured, the verified and refused
- * deliveries, and the finds of the pass over every repository (at the start and when the receiver listens) that no event said. **A forge whose events stop is said** (issue 729): once the receiver
+ * deliveries, and the polls' finds no event said. **A forge whose events stop is said** (issue 729): once the receiver
  * listens and the hook is ensured, when nothing verified for ten minutes — since the start, or since the last delivery —
- * and a pass has found at least two heads or merges no event said in that quiet (one could be a pass beating an
+ * and the poll has found at least two heads or merges no event said in that quiet (one could be the poll beating an
  * event by a second), it is logged loudly once per silent spell, and the module's events are said unhealthy until a
  * delivery verifies. Deliveries refused since the last verified one are said unhealthy too.
  */
@@ -317,7 +318,7 @@ export class Pace {
     this.notHeard = null;
   }
   /** No events are listened for, and why: by configuration (`fails` false), or because the receiver could not listen
-   *  or the hook could not be ensured (`fails` true, said unhealthy). Only the pass at the start watches. */
+   *  or the hook could not be ensured (`fails` true, said unhealthy). The polls alone watch. */
   unheard(why: string, fails = true): void {
     this.notHeard = why;
     this.notHeardFails = fails;
@@ -336,10 +337,10 @@ export class Pace {
     this.refusedSpell++;
     this.lastRefused = { at: this.now(), reason, from };
   }
-  /** The pass over every repository found a head or merge no forge event announced. */
+  /** The poll found a head or merge no forge event announced. */
   miss(what: string): void {
     const t = this.now();
-    if (this.hearing()) this.log(`THE FORGE'S EVENTS MISSED ${what}: the pass over every repository found it`);
+    if (this.hearing()) this.log(`THE FORGE'S EVENTS MISSED ${what}: the poll found it, so the polls look every 30 s again until the next event`);
     this.missed = t;
     this.missCount++;
     this.lastMiss = { at: t, what };
@@ -354,8 +355,8 @@ export class Pace {
       this.log(`THE FORGE'S EVENTS ARE NOT HEARD: ${this.last ? `no delivery verified since the last at ` +
         `${new Date(this.last).toISOString()}` : "no delivery ever verified since the start"}, ${minutes} min, from the ` +
         `system webhook at ${this.hook?.url}${refusedSince ? `; ${refusedSince} refused since, the last because ` +
-        `${this.lastRefused?.reason}` : ""}; the pass found ${what}; nothing else watches the forge ` +
-        `(novox/hq issue 729, 1422)`);
+        `${this.lastRefused?.reason}` : ""}; the poll found ${what} — the polls alone watch the forge, every 30 s ` +
+        `(novox/hq issue 729)`);
     }
   }
   /** Whether a delivery was refused after the last verified one (or with none verified). */
@@ -366,6 +367,9 @@ export class Pace {
     const t = this.now();
     return this.last > 0 && t - this.last < 10 * 60_000 && this.last > this.missed;
   }
+  every(): number {
+    return this.hearing() ? 5 * 60_000 : 30_000;
+  }
   private expecting(): boolean {
     return this.where !== null && this.hook !== null;
   }
@@ -379,14 +383,14 @@ export class Pace {
     if (this.silentSince) {
       state = "unhealthy";
       why = `${this.last ? `no delivery verified since the last at ${iso(this.last)}` : `the forge has never delivered an ` +
-        `event since the start at ${iso(this.started)}`}, while the pass found ${this.missCount} head(s) or merge(s) no ` +
+        `event since the start at ${iso(this.started)}`}, while the poll found ${this.missCount} head(s) or merge(s) no ` +
         `event said, the last ${this.lastMiss?.what} at ${iso(this.lastMiss?.at ?? t)}`;
     } else if (refusedSince) {
       state = "unhealthy";
       why = `${refusedSince} deliveries refused ${this.last ? `since the last verified one at ${iso(this.last)}` :
         "and none verified"}, the last at ${iso(this.lastRefused?.at ?? t)} because ${this.lastRefused?.reason}`;
     } else if (!this.expecting()) {
-      why = this.notHeard ? `no events are listened for, so only the pass at the start watches the forge: ${this.notHeard}` :
+      why = this.notHeard ? `no events are listened for, so the polls alone watch the forge: ${this.notHeard}` :
         "the receiver is not listening yet";
       if (this.notHeard && this.notHeardFails) state = "unhealthy";
     } else if (this.hearing()) {
@@ -394,7 +398,7 @@ export class Pace {
     } else if (this.last === 0) {
       why = `no delivery heard yet; the forge is said silent if the poll finds what no event said ${SILENT_AFTER / 60_000} min after the start`;
     } else {
-      why = `the last delivery was at ${iso(this.last)}; nothing polls the forge, so what happens meanwhile is announced at the next start or when the receiver listens again`;
+      why = `the last delivery was at ${iso(this.last)}; the polls look every 30 s until the next`;
     }
     return {
       healthy: state !== "unhealthy", state, why,
@@ -403,8 +407,7 @@ export class Pace {
       hook: this.hook,
       verified: { count: this.verifiedCount, last: this.lastVerified && { ...this.lastVerified, at: iso(this.lastVerified.at) } },
       refused: { count: this.refusedCount, since_verified: refusedSince, last: this.lastRefused && { ...this.lastRefused, at: iso(this.lastRefused.at) } },
-      polls: { every_seconds: null, note: "no timer asks the forge; one pass at the start and when the receiver listens (issue 1422)",
-        hearing: this.hearing(), found_unsaid: this.missCount,
+      polls: { every_seconds: this.every() / 1000, hearing: this.hearing(), found_unsaid: this.missCount,
         last_found: this.lastMiss && { ...this.lastMiss, at: iso(this.lastMiss.at) } },
       silent: this.silentSince ? { since: iso(this.silentSince) } : null,
     };
@@ -499,8 +502,8 @@ export function eventsTool(pace: Pace): { name: string; description: string; inp
     name: "gitea_events",
     description: "Whether the forge's events reach the mesh (novox/hq issue 729): where the receiver listens, the " +
       "system webhook as ensured at the start (its id, url, events, kind, and what it replaced), how many deliveries " +
-      "verified and the last one's time and event, how many were refused and the last reason, whether " +
-      "events are heard (nothing polls; one pass runs at the start), and how many heads or merges that pass found that no event said. Unhealthy when the " +
+      "verified and the last one's time and event, how many were refused and the last reason, how often the polls look " +
+      "and whether events are heard, and how many heads or merges the poll found that no event said. Unhealthy when the " +
       "forge has delivered nothing that verified for ten minutes (since the start or since the last delivery) while the " +
       "poll found what no event said, when deliveries were refused since the last verified one, or when the receiver " +
       "could not listen or the webhook could not be made.",

modules/mesh-catalog/store.ts

@@ -66,7 +66,7 @@ CREATE TABLE IF NOT EXISTS module_version (
   PRIMARY KEY (module, commit_sha)
 );
 
--- What the catalog considers this module to be now. Separate from module_version because a
+-- What the catalogue considers this module to be now. Separate from module_version because a
 -- module has many versions and exactly one current one, and "current" is a decision rather than
 -- a consequence of being newest.
 CREATE TABLE IF NOT EXISTS module_current (
@@ -144,7 +144,7 @@ export class Graph {
     const url = env["DATABASE_URL"] ?? readMaybe(env["DATABASE_URL_FILE"]);
     if (!url) {
       throw new Error(
-        "no DATABASE_URL: the catalog holds the module graph and cannot hold it in memory, " +
+        "no DATABASE_URL: the catalogue holds the module graph and cannot hold it in memory, " +
           "because a graph that disappears on restart is not a record of anything",
       );
     }
@@ -246,7 +246,7 @@ export class Graph {
     }
   }
 
-  /** Every module the catalog holds, with the commit it considers current. */
+  /** Every module the catalogue holds, with the commit it considers current. */
   async modules(): Promise<{ module: string; commit: string; repository: string; path: string }[]> {
     const { rows } = await this.pool.query(
       `SELECT c.module, c.commit_sha, v.repository, v.path

modules/mesh-catalog/tools/index.ts

@@ -12,7 +12,7 @@ export function getCatalogueTools(graph: Graph): ToolDefinition[] {
     {
       name: "catalog_modules",
       description:
-        "Every module this mesh holds, with the commit the catalog considers current and where it came from.",
+        "Every module this mesh holds, with the commit the catalogue considers current and where it came from.",
       input: {},
       run: async () => ({ modules: await graph.modules() }),
     },
@@ -28,7 +28,7 @@ export function getCatalogueTools(graph: Graph): ToolDefinition[] {
         const module = String(args.module ?? "");
         if (!module) return { error: "name a module" };
         const found = await graph.show(module, args.commit ? String(args.commit) : undefined);
-        return found ? { module: found } : { error: `the catalog holds no ${module}` };
+        return found ? { module: found } : { error: `the catalogue holds no ${module}` };
       },
     },
     {

modules/mesh-config/cmd/mesh-config/config.go

@@ -184,7 +184,7 @@ func (call Call) level() (Level, error) {
 	case call.Module != "":
 		return Level{}, fmt.Errorf("a module's own value is set for one node, and no node is named: there is no "+
 			"module value for the whole mesh (novox/hq ADR 0348 §3); name the node, or set mesh config for the "+
-			"predefined key %s's value falls back to, or change its default in the catalog", call.Module)
+			"predefined key %s's value falls back to, or change its default in the catalogue", call.Module)
 	case call.Node != "":
 		return Level{Kind: LevelNode, Node: call.Node}, nil
 	}

modules/mesh-config/cmd/mesh-config/sources.go

@@ -27,7 +27,7 @@ func (c *Config) sources() (Sources, error) {
 	}); err != nil {
 		return s, fmt.Errorf("the assignments cannot be read: %w", err)
 	}
-	// And every module the catalog's placement names on a node (ADR 0549 §3): until ADR 0547's third milestone both
+	// And every module the catalogue's placement names on a node (ADR 0549 §3): until ADR 0547's third milestone both
 	// sources stand (ADR 0549 §5), so a pair either names is resolved, and none loses its values while the two differ.
 	// Placement that cannot be read yet (the indexer's state not on the bus) leaves the assignments alone, said.
 	standing := map[string]bool{}
@@ -57,7 +57,7 @@ func (c *Config) sources() (Sources, error) {
 		}
 		return nil
 	}); err != nil {
-		problems = append(problems, fmt.Sprintf("the catalog's placement cannot be read, so the assignments alone are resolved: %v", err))
+		problems = append(problems, fmt.Sprintf("the catalogue's placement cannot be read, so the assignments alone are resolved: %v", err))
 	}
 	if err := c.each(DeclaredConfigRead, func(key string, raw []byte) error {
 		m, err := ParseModuleDeclarations(raw)

modules/mesh-issues/cmd/mesh-issues/tracker.go

@@ -559,7 +559,7 @@ func cycleRules(is *Issue, from, to string) error {
 		}
 		if IsCore(is.LocatedIn) && is.Replay == "" && is.ReplayNone == "" {
 			return fmt.Errorf("issue %d is a core issue (it is located in the controller, the node-engine, the tool "+
-				"runner, the SDK, the delivery parts, or the catalog's bus, forge or build modules): it resolves with replay, the replay's id "+
+				"runner, the SDK, the delivery parts, or the catalogue's bus, forge or build modules): it resolves with replay, the replay's id "+
 				"in mesh-lab's replays register, or replay-none, why no replay is possible (ADR 0237)", is.Number)
 		}
 	case StatusWontfix:

retired-words

@@ -2,7 +2,6 @@
 # *Not:* words with no scope or with (tools). A copy, so a catalogue merge needs nothing else; novox/hq's
 # words.py compares it with the glossary. Regenerate with: python3 00-META/checks/words.py --list tools
 build machine
-catalogue
 change plan
 control plane
 flavor