@event4u/agent-config 14.10.0 → 14.11.0

package/src/scripts/schemas/fidelity-measurement-sheet.schema.json

@@ -0,0 +1,169 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "fidelity-measurement-sheet.schema.json",
+  "title": "Fidelity measurement sheet",
+  "description": "The per-element artefact W3 of road-to-frontend-fidelity-calibration records as absent: a tree-wide search for `measurement-sheet` / `measurement_sheet` / `per-element measurement` across src/ and docs/ returned zero hits at 2026-08-22. One row per (selector, dimension) pair carrying the expected value, the observed value, and — the part that makes it a fidelity artefact rather than a diff — WHERE the expectation came from. A reviewer can diff two sheets and a gate can read the `status` column, neither of which is true of an agent comparing two pictures. Deliberately NOT a findings format: `review-findings.schema.json` already owns findings. A sheet is the measurement; a finding is what someone decided about it.",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "dimensions",
+    "rows"
+  ],
+  "additionalProperties": true,
+  "properties": {
+    "schema_version": {
+      "enum": [
+        1
+      ],
+      "description": "Pinned. Spelled as a one-member `enum` rather than `const` because this repo's Draft-07 subset validator (validate_frontmatter.ts) enforces `enum` and silently ignores `const` — a `const` here would be a pin nothing checks."
+    },
+    "surface": {
+      "type": "string",
+      "description": "What was measured — a route, a component path, or a fixture id. Free text; no gate reads it."
+    },
+    "captured_at": {
+      "type": "string",
+      "description": "ISO-8601 timestamp of the measurement run."
+    },
+    "dimensions": {
+      "type": "array",
+      "minItems": 1,
+      "description": "Every dimension this sheet accounts for — shipped and cut alike. AC-3 is checked against this list: each entry is either measured by >=1 row or carries a `null_record`. A dimension that appears in neither is the failure the AC exists to catch.",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "status"
+        ],
+        "additionalProperties": true,
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Stable dimension id, e.g. `token-literal`. Rows reference it."
+          },
+          "status": {
+            "enum": [
+              "shipped",
+              "null"
+            ],
+            "description": "`shipped` — at least one row carries a measurement for it. `null` — cut, and `null_record` says which pre-registered falsifier fired."
+          },
+          "null_record": {
+            "type": "object",
+            "required": [
+              "falsifier",
+              "unavailable_capability",
+              "affected_claims",
+              "reopening_condition"
+            ],
+            "additionalProperties": true,
+            "description": "Required when `status` is `null`. The four parts this roadmap records for every null, so a cut dimension is distinguishable from one nobody thought of.",
+            "properties": {
+              "falsifier": {
+                "type": "string",
+                "description": "The pre-registered falsifier id from the Phase 2.3 list that fired."
+              },
+              "unavailable_capability": {
+                "type": "string",
+                "description": "What is missing, named as a capability rather than as an excuse."
+              },
+              "affected_claims": {
+                "type": "array",
+                "items": { "type": "string" },
+                "description": "Inventory row ids (A1..A13) this null covers. A null that enumerates nothing is indistinguishable from a matrix that never had those rows."
+              },
+              "reopening_condition": {
+                "type": "string",
+                "description": "The observable event that puts the dimension back in the matrix."
+              }
+            }
+          }
+        }
+      }
+    },
+    "rows": {
+      "type": "array",
+      "description": "The measurements. May be empty only when every dimension carries `status: null`.",
+      "items": {
+        "type": "object",
+        "required": [
+          "selector",
+          "dimension",
+          "expected",
+          "observed",
+          "expectation_source",
+          "status"
+        ],
+        "additionalProperties": true,
+        "properties": {
+          "selector": {
+            "type": "string",
+            "description": "What was measured — a CSS selector where a page was reached, otherwise a `file:line` anchor. Both are per-element; only one of them needs a browser."
+          },
+          "dimension": {
+            "type": "string",
+            "description": "The `dimensions[].id` this row measures."
+          },
+          "expected": {
+            "type": [
+              "string",
+              "number",
+              "null"
+            ],
+            "description": "The value the expectation source calls for. `null` means the source is silent, which is a legitimate measurement — see `status: unspecified`."
+          },
+          "observed": {
+            "type": [
+              "string",
+              "number",
+              "null"
+            ],
+            "description": "The value actually present."
+          },
+          "expectation_source": {
+            "type": "object",
+            "required": [
+              "kind",
+              "ref"
+            ],
+            "additionalProperties": true,
+            "description": "VALUE-LEVEL provenance. `docs/guidelines/design-fidelity-mechanics.md` carries the finding-level `artifact_covered` flag; this is the finer grain that answers `where did this 16px come from`, which a per-finding boolean cannot.",
+            "properties": {
+              "kind": {
+                "enum": [
+                  "provided_artifact",
+                  "design_token",
+                  "brand_token",
+                  "house_heuristic",
+                  "agent_inference"
+                ],
+                "description": "Ordered by authority, highest first, mirroring the precedence chain rather than restating it. `agent_inference` is the lowest and is the one a reviewer should be able to find by filtering."
+              },
+              "ref": {
+                "type": "string",
+                "description": "Where exactly — a token name, a `file:line`, or an artefact anchor. Never a bare `true`."
+              },
+              "artifact_covered": {
+                "type": "boolean",
+                "description": "Mirrors `ARTIFACT_COVERED_KEY` for the row's own value. Optional and defaulted-absent: the coarse per-finding flag stays the default channel, and this field never replaces it."
+              }
+            }
+          },
+          "status": {
+            "enum": [
+              "match",
+              "deviation",
+              "unspecified",
+              "unmeasured"
+            ],
+            "description": "`match` / `deviation` — expected and observed both known. `unspecified` — the source is silent, so there is nothing to deviate from. `unmeasured` — the dimension is blocked; the row records that it was not skipped silently."
+          },
+          "blocker": {
+            "type": "string",
+            "description": "Required in practice when `status` is `unmeasured`: the blocker slug, e.g. `b-page-capture-primitive`. Not schema-required, because a sheet produced outside this roadmap has no blocker file to name."
+          }
+        }
+      }
+    }
+  }
+}

package/src/scripts/schemas/rule.schema.json

@@ -55,6 +55,28 @@
       },
       "description": "Eager auto-loaded context references. Same logical-name rule as `load_context`. Counts against the per-rule char budget; enforced by scripts/lint_load_context.py."
     },
+    "norm": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["tokens", "remainder"],
+      "description": "The rule's declared NORMATIVE budget, plus where its non-normative remainder went. Optional: a required key would red every existing rule file on the day it lands, which is the gate-that-teaches-you-to-ignore-it failure `src/config/preamble-payload-budget.json` warns about in its own `_comment`. A rule that declares this is asserting that everything left in its body is obligation or routing, and that the rationale a reader may still want is reachable at `remainder`. Measured and enforced by `lint_rule_norm_pin`.",
+      "properties": {
+        "tokens": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Exact-BPE ceiling (cl100k_base) for the rule body BELOW the frontmatter. Never a chars/4 proxy - this tree ships an exact tokenizer and a pin measured in the other unit would be enforced against a number nobody can reproduce. Derive it from a real measurement of the rule after its remainder has moved out; a pin invented at authoring time is an invented threshold and the lint would then enforce a guess."
+        },
+        "remainder": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "pattern": "^((\\.\\./)*(contexts|docs|skills)/|agents/settings/contexts/|dist/agent-src/(contexts|skills)/)[^\\s]+\\.md$"
+          },
+          "description": "Where the prose this rule used to carry now lives - one or more guideline, context, or skill paths. REQUIRED alongside `tokens`, deliberately: a pin with no destination is a licence to delete, and `preservation-guard` forbids deletion during a transformation. The rule must also carry an inbound link to each entry so the relocated prose stays reachable (`check_references`)."
+        }
+      }
+    },
     "tier": {
       "type": "string",
       "enum": ["1", "2a", "2b", "3", "safety-floor", "mechanical-already", "kernel", "tier-1", "tier-2"],
@@ -150,9 +172,9 @@
       "uniqueItems": true,
       "items": {
         "type": "string",
-        "pattern": "^(hook:[a-z0-9_-]+|validator:[A-Za-z0-9_./-]+|test:[A-Za-z0-9_./-]+|observer:[a-z0-9 _-]+|none)$"
+        "pattern": "^(hook:[a-z0-9_-]+|validator:[A-Za-z0-9_./-]+|test:[A-Za-z0-9_./-]+|observer:[a-z0-9 _-]+|instruction-only: *[^ ].*|none)$"
       },
-      "description": "What mechanically enforces this rule. `validator:<script>` and `test:<path>` must resolve on disk AND be wired into a taskfile, workflow, or the hook manifest — a script that exists but runs nowhere resolves to unwired, not covered. `hook:<name>` must be registered in hook_manifest.yaml with fail_closed: true; a hook that never blocks is `observer:`, not `validator:`. `none` is legal and counted — an honest gap beats a false claim. Resolved, not trusted, by check_enforcement_coverage.ts."
+      "description": "What mechanically enforces this rule. `validator:<script>` and `test:<path>` must resolve on disk AND be wired into a taskfile, workflow, or the hook manifest — a script that exists but runs nowhere resolves to unwired, not covered. `hook:<name>` must be registered in hook_manifest.yaml with fail_closed: true; a hook that never blocks is `observer:`, not `validator:`. `instruction-only: <reason>` declares an honestly model-carried obligation and is counted as a recorded gap — the reason is MANDATORY in the pattern, because a bare marker is a claim with no triage record behind it and resolves to `missing`, which the --check ratchet reds on. The bare `none` spelling it replaces stays legal for exactly one reason: `non-destructive-by-default` still carries it and is a kernel rule that block_kernel_rule_writes denies agent writes to, so retiring the value outright would make a CI-green tree unreachable for any agent. Resolved, not trusted, by check_enforcement_coverage.ts."
     },
     "obligation_frequency": {
       "type": "string",

package/src/scripts/schemas/skill.schema.json

@@ -287,6 +287,45 @@
         }
       }
     },
+    "scope": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "OPTIONAL write-scope declaration. Measured 2026-08-23: 0 of 292 SKILL.md files said WHERE a skill may write — `execution:` carries type / handler / timeout_seconds / allowed_tools and `trust:` carries level / removable / default, and none of them answers that question. This is a DECLARATION and a census, not a runtime control: nothing observes a skill's writes, `skill_linter` validates the SHAPE only, and absence stays legal. Saying so is the point — an optional field described as if it constrained anything would be exactly the coverage inflation this repository's enforcement doctrine forbids. Derive it, never guess it: for `handler: shell` the `command:` array names the script whose writes ARE the scope; for `handler: internal` and for a bare `type: manual` the skill executes nothing itself, so an empty `write` list plus a `verification_reason` is the accurate declaration rather than a placeholder.",
+      "properties": {
+        "read": {
+          "type": "array",
+          "items": {"type": "string"},
+          "description": "Repo-relative globs the skill reads. Optional — omit rather than guess; an invented read set is worse than an absent one."
+        },
+        "write": {
+          "type": "array",
+          "description": "Write paths this skill's OWN execution touches. An empty list is a real statement — \"this skill declares no write path of its own\" — and is falsified by any write its execution performs.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["pattern", "access"],
+            "properties": {
+              "pattern": {"type": "string", "minLength": 1, "description": "Repo-relative glob the skill may write."},
+              "access": {
+                "type": "string",
+                "enum": ["create", "write", "append", "delete"],
+                "description": "Closed enum. `create` = new paths only · `write` = create or overwrite · `append` = never rewrites existing bytes · `delete` = removes paths. A value outside the enum is a skill_linter error."
+              }
+            }
+          }
+        },
+        "verification_command": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The command that proves the declared scope is what the skill actually touches. Exactly one of `verification_command` / `verification_reason` is present when `scope:` is — enforced by skill_linter's `scope_verification` check, not by this schema, because JSON Schema cannot express \"exactly one of these two optional siblings\" in a form this repo's frontmatter validator implements."
+        },
+        "verification_reason": {
+          "type": "string",
+          "minLength": 1,
+          "description": "An HONEST NULL at declaration level: why no command can prove this scope. The pair is deliberately TWO sibling keys rather than a nested `verification: {command|reason}` map, and the reason is measured rather than stylistic: this repo's frontmatter parser reads map -> list -> map (that is how `triggers[].keyword` works) but flattens map -> map -> scalar, so a nested `verification.reason` parses as `scope.verification = \"\"` plus a stray `scope.reason` and the schema then rejects a correctly-written declaration. A field the parser cannot read is a field nothing validates."
+        }
+      }
+    },
     "triggers": {
       "type": "array",
       "minItems": 1,

package/src/scripts/schemas/ui-authority.schema.json

@@ -0,0 +1,114 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://event4u.dev/schemas/ui-authority.schema.json",
+  "title": "ui_authority",
+  "description": "The ONE authority object for a UI surface. Produced once before design and read by every UI phase and by the stop gate. Contract: docs/contracts/ui-authority.md. There is deliberately no second partial decision table anywhere in src/skills/ — A1.1's verify line asserts that.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "surface_mode",
+    "register",
+    "change_intent",
+    "reference_maturity",
+    "primary_source",
+    "constraints",
+    "conflicts",
+    "provenance",
+    "verification"
+  ],
+  "properties": {
+    "surface_mode": {
+      "description": "What the surface is FOR. Per-surface, never inherited from PRODUCT.md.",
+      "enum": ["persuade", "operate", "read", "experience"]
+    },
+    "register": {
+      "description": "The design register, unchanged from docs/guidelines/design-modes.md.",
+      "enum": ["brand", "product"]
+    },
+    "change_intent": {
+      "description": "What the run is authorised to move. `preserve` is the strongest constraint and drives the intent-aware stop gate.",
+      "enum": ["preserve", "extend", "redesign", "new-world"]
+    },
+    "reference_maturity": {
+      "description": "How finished the supplied reference is. `wireframe` declares STRUCTURE and never a pixel mandate. `null` means no reference was supplied.",
+      "enum": [
+        "wireframe",
+        "prototype",
+        "finished-comp",
+        "runnable-artifact",
+        "production-incumbent",
+        null
+      ]
+    },
+    "fidelity_mandate": {
+      "description": "Carried from road-to-frontend-fidelity-calibration Phase 0. NOT re-derived here — this field holds that phase's output, and null means that phase has not produced one.",
+      "type": ["string", "null"]
+    },
+    "primary_source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind"],
+      "properties": {
+        "kind": {
+          "description": "Which authority the run builds from. `incumbent` is the answer when no DESIGN.md exists but a coherent incumbent does.",
+          "enum": ["user-instruction", "artifact", "comp", "design-system", "incumbent", "brief", "none"]
+        },
+        "path": { "type": ["string", "null"] }
+      }
+    },
+    "constraints": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "preserve_palette": { "type": "boolean" },
+        "preserve_type_family": { "type": "boolean" },
+        "preserve_layout": { "type": "boolean" },
+        "preserve_copy": { "type": "boolean" }
+      }
+    },
+    "conflicts": {
+      "description": "Surfaced disagreements. A conflict is REPORTED, never silently resolved — an operation whose declared dimensions collide with a constraint appends here and performs no write.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["dimension", "wanted", "blocked_by"],
+        "properties": {
+          "dimension": { "type": "string" },
+          "wanted": { "type": "string" },
+          "blocked_by": { "type": "string" }
+        }
+      }
+    },
+    "provenance": {
+      "description": "Where each resolved value came from. One entry per resolved field, so a wrong resolution is traceable to its signal rather than to the resolver as a whole.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["field", "source"],
+        "properties": {
+          "field": { "type": "string" },
+          "source": {
+            "enum": ["user-instruction", "surface-brief", "design-md", "product-md", "incumbent-scan", "reference-artifact", "default"]
+          },
+          "detail": { "type": ["string", "null"] }
+        }
+      }
+    },
+    "verification": {
+      "description": "Graft 2 of the parent roadmap. A pass that could not fully run says so rather than passing silently.",
+      "enum": ["verified", "degraded", "unverified"]
+    },
+    "degradation_reason": {
+      "description": "Required whenever `verification` is not `verified`. The resolver refuses to emit a degraded object without one.",
+      "type": ["string", "null"]
+    }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "verification": { "enum": ["degraded", "unverified"] } }, "required": ["verification"] },
+      "then": { "properties": { "degradation_reason": { "type": "string", "minLength": 1 } }, "required": ["degradation_reason"] }
+    }
+  ]
+}

package/src/scripts/session_register_hook.ts

@@ -209,6 +209,8 @@ export interface RoadmapClaim {
     slug: string;
     written_at?: string;
     session_id?: string | null;
+    /** Repo-relative paths the claiming session declared it owns. */
+    paths?: string[];
 }
 
 function _is_replay_mode(): boolean {
@@ -227,9 +229,14 @@ function _read_claim_file(file: string): RoadmapClaim | null {
             return null;
         }
         const sid = rec['session_id'];
+        const raw_paths = rec['paths'];
+        const paths = Array.isArray(raw_paths)
+            ? raw_paths.filter((x): x is string => typeof x === 'string' && x.trim() !== '')
+            : [];
         return {
             slug: slug.trim(),
             ...(typeof sid === 'string' && sid.trim() !== '' ? { session_id: sid.trim() } : {}),
+            ...(paths.length > 0 ? { paths } : {}),
         };
     } catch {
         return null;
@@ -249,6 +256,8 @@ export interface ResolvedClaim {
     slug: string;
     /** Absolute path of the claim file this read came from. */
     path: string;
+    /** Repo-relative paths the claim declared, or absent when it declared none. */
+    paths?: string[];
 }
 
 /**
@@ -278,7 +287,13 @@ export function resolve_claim(
         for (const p of claim_read_paths(workspace_root, session_id)) {
             if (path.basename(p) === path.basename(ROADMAP_CLAIM_REL)) continue;
             const mine = _read_claim_file(p);
-            if (mine !== null) return { slug: mine.slug, path: p };
+            if (mine !== null) {
+                return {
+                    slug: mine.slug,
+                    path: p,
+                    ...(mine.paths !== undefined ? { paths: mine.paths } : {}),
+                };
+            }
         }
     }
     // The legacy per-WORKTREE file, in the same two locations. Unchanged in
@@ -313,7 +328,11 @@ export function resolve_claim(
     if (id !== '') {
         return null;
     }
-    return { slug: legacy.slug, path: legacy_path };
+    return {
+        slug: legacy.slug,
+        path: legacy_path,
+        ...(legacy.paths !== undefined ? { paths: legacy.paths } : {}),
+    };
 }
 
 /**
@@ -530,12 +549,13 @@ export function build_record(
     started_at: string,
     now: Date = new Date(),
 ): SessionRecord {
+    const claim = resolve_claim(workspace_root, session_id);
     const rec: SessionRecord = {
         session_id,
         platform,
         worktree: workspace_root,
         branch: current_branch(workspace_root),
-        roadmap_slug: read_claimed_slug(workspace_root, session_id),
+        roadmap_slug: claim?.slug ?? null,
         started_at,
         last_seen: iso_now(now),
     };
@@ -552,6 +572,12 @@ export function build_record(
         }
         if (Object.keys(nonZero).length > 0) rec.turn_end_refusals = nonZero;
     }
+    // road-to-roadmap-situational-awareness § 3.1 — the path axis, on exactly the
+    // terms above: only ever ADDS a field, so a session that declared no paths
+    // writes the record it wrote before this existed, byte for byte.
+    if (claim?.paths !== undefined && claim.paths.length > 0) {
+        rec.owned_paths = [...claim.paths].sort();
+    }
     return rec;
 }
 

package/src/scripts/sessions_cli.ts

@@ -45,12 +45,14 @@ import { fileURLToPath } from 'node:url';
 
 import { write_atomic } from './_lib/fs_atomic.js';
 import {
+    classify_collisions,
     iso_now,
     read_live_records,
     register_dir,
     safe_stem,
     ttl_is_measured,
     ttl_seconds_for,
+    type SessionRecord,
 } from './_lib/session_register.js';
 import { claim_file, claim_is_stale, claim_read_paths } from './session_register_hook.js';
 
@@ -62,7 +64,7 @@ function usage(): number {
             '                                           live sessions, plus unmerged branches',
             '                                           held by other worktrees (--branches adds',
             '                                           that axis to the JSON form)',
-            '  agent-config sessions:claim <slug>       claim a roadmap for this session',
+            '  agent-config sessions:claim <slug> [--paths <a,b,…>]       claim a roadmap for this session',
             '  agent-config sessions:claim <slug> --force   claim it even though a peer holds it',
             '  agent-config sessions:claim --release    drop this session\'s roadmap claim',
             '',
@@ -168,6 +170,30 @@ export function other_worktree_branches_detailed(
     return { rows, filtered: unmerged !== null };
 }
 
+/**
+ * `PATH OVERLAP` lines for this session against every live peer.
+ *
+ * Kept a separate, separately-labelled line rather than folded into the slug or
+ * branch report, because the three collisions call for three different moves: a
+ * slug collision means stop, a branch collision means coordinate, a path
+ * collision means reorder — take the disjoint steps first if ordering allows,
+ * otherwise name it and continue. The register is advisory and never a lock.
+ *
+ * Pure over the record arrays so the fixture test needs no register on disk.
+ */
+export function path_overlap_lines(
+    others: readonly SessionRecord[],
+    here: { branch: string | null; roadmap_slug: string | null; owned_paths?: readonly string[] },
+): string[] {
+    return classify_collisions(others, here)
+        .filter((c) => c.kind === 'path')
+        .map(
+            (c) =>
+                `  PATH OVERLAP  ${c.record.session_id}  ·  ${(c.paths ?? []).length} shared path(s): ` +
+                `${(c.paths ?? []).join(', ')}`,
+        );
+}
+
 function cmd_list(argv: string[], root: string): number {
     const as_json = argv.includes('--json');
     const dir = register_dir(root);
@@ -229,6 +255,21 @@ function cmd_list(argv: string[], root: string): number {
         );
     }
     write_held_branches(held, filtered);
+    // The path axis. Silent when this session has declared no owned paths, which
+    // is every session that has not run `sessions:claim --paths`.
+    const sid = env_session_id();
+    const mine = sid === null ? undefined : records.find((r) => r.session_id === sid);
+    const overlaps = path_overlap_lines(
+        records.filter((r) => r.session_id !== mine?.session_id),
+        {
+            branch: mine?.branch ?? null,
+            roadmap_slug: mine?.roadmap_slug ?? null,
+            ...(mine?.owned_paths !== undefined ? { owned_paths: mine.owned_paths } : {}),
+        },
+    );
+    if (overlaps.length > 0) {
+        process.stdout.write(`\n${overlaps.join('\n')}\n`);
+    }
     process.stdout.write(
         'Advisory only — this register is not a lock, and an idle session\n' +
             'disappears from it after its TTL although its user may return.\n',
@@ -432,7 +473,15 @@ function cmd_claim(argv: string[], root: string): number {
         );
         return 0;
     }
-    const slug = argv.find((a) => !a.startsWith('-'));
+    const paths_idx = argv.indexOf('--paths');
+    const paths_arg = paths_idx >= 0 ? (argv[paths_idx + 1] ?? '') : '';
+    const owned_paths = paths_arg
+        .split(',')
+        .map((x) => x.trim())
+        .filter((x) => x !== '');
+    // The slug is the first bare token that is not the VALUE of --paths; without
+    // this the comma list would be read as the slug on `claim --paths a,b road-to-x`.
+    const slug = argv.find((a, i) => !a.startsWith('-') && i !== paths_idx + 1);
     if (slug === undefined || slug.trim() === '') {
         return usage();
     }
@@ -476,7 +525,19 @@ function cmd_claim(argv: string[], root: string): number {
     try {
         write_atomic(
             target,
-            `${JSON.stringify({ slug: slug.trim(), written_at: iso_now(), session_id: sid }, null, 2)}\n`,
+            `${JSON.stringify(
+                {
+                    slug: slug.trim(),
+                    written_at: iso_now(),
+                    session_id: sid,
+                    // Absent, not empty, when nothing was declared: the whole
+                    // additive guarantee of `owned_paths` rests on the field not
+                    // being written at all in the ordinary case.
+                    ...(owned_paths.length > 0 ? { paths: owned_paths } : {}),
+                },
+                null,
+                2,
+            )}\n`,
         );
     } catch (exc) {
         process.stderr.write(`sessions:claim: could not write the claim — ${String(exc)}\n`);
@@ -484,6 +545,9 @@ function cmd_claim(argv: string[], root: string): number {
     }
     process.stdout.write(
         `Claimed "${slug.trim()}" for this session. It becomes visible to other\n` +
+            (owned_paths.length > 0
+                ? `Declared ${owned_paths.length} owned path(s); peers sharing one are labelled PATH OVERLAP.\n`
+                : '') +
             'sessions on the next turn, when the heartbeat lifts it into the register.\n' +
             (sid === null
                 ? 'NOTE: this host exports no session id, so the claim is scoped to this\n' +