fix(agent): publish honours the managed-by ownership marker (closes #486)

`agent publish` rewrites a whole declaration, so it was the widest st2 write path onto the very bytes `agent desired-state --managed-by` guards (#473): any local writer could replace a Nix-owned declaration wholesale.

The incumbent's ownership marker now governs the replacement, through the same authority and the same refusal codes the lifecycle verb uses. Creation and a byte-identical republication replace no owned bytes and stay open, and the unasserted refusal stays scoped to `nix` so publishers of other markers adopt the assertion on their own schedule.

agent-identity: dev3.direct.omp.43sz6ujq
agent-persona: generalist
agent-supervisor: unavailable
agent-tool: OMP
agent-tool-version: 18.1.7
agent-runtime: OMP 18.1.7
tooling-profile: dotfiles@39a19af

Author: schickling-assistant

INVARIANTS.md

@@ -43,5 +43,5 @@ materialization, messaging, DING, or presence must preserve them.
 | **Pass progress is independent of publication** | A reconcile pass completes whether or not resync publication is making progress. Publication runs on its own thread, so a pass's per-seat watch-set handshakes never wait for a catalog lock, a stream lock, or a refused publication. One publication is outstanding per subscription at a time, and a queued publication is dropped when its subscription is deactivated or removed by a refresh, so nothing is published to a seat the pass has already decided receives no events. | `src/run.rs::reconcile_pass_completes_while_a_resync_publication_is_blocked`; `src/resync.rs::a_flush_never_hands_off_a_subscription_whose_publication_is_outstanding`; `src/resync.rs::deactivation_drops_only_that_recipients_queued_publication`; `src/resync.rs::a_refresh_drops_a_queued_publication_for_a_subscription_it_removed` |
 | **Terminal refusals are classified, not retried** | A refused resync publication is classified by what could admit it later. A recipient that is declared but not running parks its reservation: it is attempted once, captures and schedules nothing while parked, and re-arms with its exact reserved bytes when a refresh carries that recipient again. An ambiguous recipient, a foreign owning host, and an undeclared stream are permanently refused: the reservation is dropped and the carrier baseline advances so the same transition is not re-captured. Everything else, including an absent declaration, stays retryable. | `src/resync.rs::a_not_running_recipient_parks_its_reservation_and_is_attempted_once`; `src/resync.rs::a_parked_reservation_re_arms_and_replays_when_its_recipient_runs_again`; `src/resync.rs::a_permanently_refused_reservation_is_dropped_and_not_recaptured`; `src/resync.rs::refusals_are_classified_by_what_could_admit_them_later` |
 | **Unbindable session sockets fail at admission** | Host-scoped validation rejects a pty task whose session socket path would exceed the portable 104-byte `sun_path` bound, because `pty` refuses that bind and the task can then never spawn. The bound is derived from the pty root resolved for the selected host rather than a fixed identity length, only that host's pty tasks are judged against it, and the diagnostic names the resolved path and the byte overage. A park whose cause is that same unbindable path does not advise `st2 unpark`, which would relaunch into the identical failure. | `tests/validate.rs::an_unbindable_session_socket_path_is_rejected_at_admission`; `tests/validate.rs::another_hosts_long_identity_is_not_judged_against_this_hosts_pty_root`; `tests/validate.rs::a_long_exec_task_id_is_not_a_socket_path_issue`; `src/run.rs::session_socket_overage_is_derived_from_the_resolved_root`; `tests/run.rs::a_structurally_unrecoverable_park_does_not_advise_unpark` |
-| **Marker-matched lifecycle authority** | A declaration carrying `meta { managed-by "nix" }` is authorable only by a caller asserting exactly the marker that declaration carries, and only through the lifecycle verb: a mismatched marker, an unmarked subject, an unresolvable multi-marker declaration, and an empty or padded assertion each refuse before any write, while presentation, address, stream, and Resource authoring refuse a Nix-owned declaration outright. A marker-matched edit rewrites nothing but the lifecycle line and is admitted through the same full-catalog gate as a compare-and-swap publication of the same bytes, so it cannot commit a declaration the catalog would reject. | `src/agent_author.rs::marker_matched_lifecycle_authority_is_exact_and_source_preserving`; `src/agent_author.rs::marker_matched_retirement_refuses_a_candidate_admission_would_reject`; `tests/agent_desired_state.rs::cli_managed_by_authority_retires_a_projected_seat_and_refuses_every_inexact_claim` |
+| **Marker-matched declaration authority** | Every st2 write path that rewrites a declaration carrying `meta { managed-by "nix" }` admits it only from a caller asserting exactly the marker that declaration carries: the lifecycle verb and the compare-and-swap `agent publish` both refuse a mismatched marker, an unmarked subject, an unresolvable multi-marker declaration, and an empty or padded assertion before any write, while presentation, address, stream, and Resource authoring refuse a Nix-owned declaration outright. Publication reads that authority from the incumbent, so creating a declaration and republishing byte-identical bytes stay open — neither replaces bytes another writer owns. A marker-matched edit rewrites nothing but the lifecycle line and is admitted through the same full-catalog gate as a compare-and-swap publication of the same bytes, so it cannot commit a declaration the catalog would reject. | `src/agent_author.rs::marker_matched_lifecycle_authority_is_exact_and_source_preserving`; `src/agent_author.rs::marker_matched_retirement_refuses_a_candidate_admission_would_reject`; `tests/agent_desired_state.rs::cli_managed_by_authority_retires_a_projected_seat_and_refuses_every_inexact_claim`; `tests/agent_publish.rs::publication_honours_the_incumbent_ownership_marker`; `tests/agent_publish.rs::publication_refuses_an_unresolvable_owner_and_repairs_unreadable_bytes` |
 | **Proof references resolve** | Every qualified test named in this table exists in its named source file, so stale invariant claims fail the suite instead of silently surviving a refactor. | `tests/invariants.rs::qualified_proof_references_resolve` |

README.md

@@ -751,7 +751,11 @@ verdict. Without the directive, Agent Spec-shaped files inside a fixture remain
 evals retain their flat bus and completion semantics.
 
 `st2 agent publish --catalog ROOT (--spec FILE | --bundle DIR) --input-sha256 HEX
-(--expect-absent | --expect-sha256 HEX)` is the single-agent declaration writer.
+(--expect-absent | --expect-sha256 HEX) [--managed-by MARKER]` is the single-agent declaration
+writer. Replacing an incumbent that carries `meta { managed-by "nix" }` requires
+`--managed-by nix`, because that publication rewrites bytes the Nix projection owns; an assertion
+is admitted only when it names exactly the marker the incumbent carries. Creating a declaration
+and republishing byte-identical bytes need no assertion.
 `st2 catalog apply --catalog ROOT
 (--prepared DIR --input-sha256 INPUT_HEX --expect-sha256 ROOT_HEX [--raw-preimage] | --resume)` is the complete
 declaration-plane writer. Each admits the complete prospective catalog under a

docs/vrs/02-agent-spec/spec.md

@@ -157,7 +157,12 @@ The st2 transaction performs these steps in order:
    external lock service, or shared receipt is involved.
 3. Re-read the current target under the lock and require the caller's exact
    absent-or-SHA-256 precondition. Require the staged digest to equal the
-   caller's input digest.
+   caller's input digest. When that incumbent carries an ownership marker and
+   the candidate would replace its bytes, require the caller to assert exactly
+   that marker with `--managed-by`: an unasserted replacement refuses for the
+   Nix marker, and a mismatched, unmarked, unresolvable, or malformed assertion
+   always refuses — here, before any write. Creation and a byte-identical
+   republication replace no owned bytes and need no assertion.
 4. Overlay the staged candidate on the locked catalog snapshot and run shared
    parsing, core admission, and st2 catalog policy over that exact projection.
 5. Publish by an atomic, durable file or bundle transition. Preserve exact

docs/vrs/requirements.md

@@ -238,6 +238,15 @@ accepted.
   yet.
   Presence, messages, context, and Resource state remain independently writable
   and are never serialized behind catalog authoring.
+  A publication that replaces an incumbent declaration carrying an ownership
+  marker is admitted only when the caller asserts exactly that marker, which
+  makes publication no weaker an authority boundary than the lifecycle verb
+  authoring the same bytes; an unasserted replacement refuses only for the Nix
+  marker, and a mismatched, unresolvable, or malformed assertion always fails
+  closed. Creating a declaration and republishing byte-identical bytes replace
+  no owned bytes and require no assertion; a candidate that merely claims a
+  marker is not an authority, so the receipt records only a marker the
+  incumbent confirmed.
   A caller binds single-agent publication to the exact no-follow source capture
   with an authoritative input digest. A canonical whole-catalog snapshot
   externalizes the declaration-root digest while excluding runtime state and

docs/vrs/spec.md

@@ -340,7 +340,8 @@ Agent Spec envelope in
 `st2 agent digest (--spec FILE | --bundle DIR)` captures a source through
 retained no-follow file descriptors and returns its authoritative digest.
 `st2 agent publish --catalog ROOT (--spec FILE | --bundle DIR)
---input-sha256 HEX (--expect-absent | --expect-sha256 HEX) --json` binds
+--input-sha256 HEX (--expect-absent | --expect-sha256 HEX)
+[--managed-by MARKER] --json` binds
 publication to that exact capture. It accepts exactly one canonical KDL `agent`
 node with an explicit ID plus path-safe host and identity. st2 no longer
 exposes an intent compiler: external renderers own the transformation from
@@ -397,6 +398,22 @@ stale declaration writer. Full-catalog admission rejects any
 structural validation error before publication. The typed result is
 `published` or `unchanged`.
 
+A hash-authorized update also passes the ownership boundary the lifecycle verb
+applies, because it rewrites the same declaration wholesale. `--managed-by
+MARKER` asserts the ownership marker the caller believes owns the incumbent,
+and the replacement is admitted only when the incumbent's own
+`meta { managed-by "..." }` names exactly that one marker; a mismatched marker,
+an unmarked incumbent, an unresolvable multi-marker incumbent, and an empty or
+padded assertion each refuse before any write, under the same refusal codes the
+authoring verbs use. Without an assertion, only the Nix marker refuses, which
+is what lets each publisher of another marker adopt the assertion on its own
+schedule. Create-only publication has no incumbent to protect and a
+byte-identical republication authors nothing, so neither requires an assertion;
+a candidate that merely claims a marker asserts no authority, and the receipt
+reports `managedBy` only for a marker the incumbent confirmed. Incumbent bytes
+that are not readable as a declaration carry no ownership claim, so repairing
+them stays possible for a writer who could already replace the file directly.
+
 Host-scoped validation rejects a pty task whose session socket path would exceed the
 portable `sun_path` bound. `pty` binds `<PTY_ROOT>/<session-id>.sock` and refuses a
 bind over the limit, so such a task can never spawn and fails identically on every

src/agent_author.rs

@@ -623,14 +623,7 @@ pub fn set_desired_state(
         validate_desired_state_reason(reason)
             .map_err(|error| AuthorError::new("invalid-desired-state", error.to_string()))?;
     }
-    if let Some(marker) = managed_by
-        && (marker.is_empty() || marker.trim() != marker)
-    {
-        return Err(AuthorError::new(
-            "invalid-managed-by",
-            format!("asserted ownership marker {marker:?} is empty or padded"),
-        ));
-    }
+    validate_marker_assertion(managed_by)?;
     let catalog_lock = CatalogLock::exclusive(catalog_root).map_err(|error| {
         AuthorError::new(
             "catalog-lock-failed",
@@ -2056,46 +2049,89 @@ fn is_nix_managed(node: &KdlNode) -> bool {
     declared_markers(node).contains(&"nix")
 }
 
-/// Decide whether `asserted` authorizes authoring on a possibly generator-owned declaration.
+/// Reject an ownership assertion no declaration could carry, before any lock or read.
+///
+/// A marker is compared byte-exactly against the declaration's own `meta { managed-by "..." }`
+/// value, so an empty or padded assertion can only ever be a caller mistake.
+pub(crate) fn validate_marker_assertion(asserted: Option<&str>) -> Result<(), AuthorError> {
+    if let Some(marker) = asserted
+        && (marker.is_empty() || marker.trim() != marker)
+    {
+        return Err(AuthorError::new(
+            "invalid-managed-by",
+            format!("asserted ownership marker {marker:?} is empty or padded"),
+        ));
+    }
+    Ok(())
+}
+
+/// Every ownership marker the declaration source `bytes` carries, in source order.
+///
+/// `agent publish` replaces a whole declaration file rather than one node, so every marker any
+/// `agent` node in the incumbent file declares is at stake in that publication and the union is
+/// what an assertion has to resolve against (#486). Bytes that are not UTF-8 or do not parse as
+/// KDL carry no discoverable claim and read as unmarked: a writer able to leave such bytes in a
+/// declaration leaf already holds direct filesystem write authority over the file, which is
+/// strictly stronger than any st2 write path this marker governs.
+pub(crate) fn declaration_markers(bytes: &[u8]) -> Vec<String> {
+    let Ok(text) = std::str::from_utf8(bytes) else {
+        return Vec::new();
+    };
+    let Ok(document) = text.parse::<KdlDocument>() else {
+        return Vec::new();
+    };
+    document
+        .nodes()
+        .iter()
+        .filter(|node| node.name().value() == "agent")
+        .flat_map(|node| {
+            declared_markers(node)
+                .into_iter()
+                .map(str::to_owned)
+                .collect::<Vec<_>>()
+        })
+        .collect()
+}
+
+/// Decide whether `asserted` authorizes rewriting bytes carrying the `declared` markers.
 ///
 /// `meta { managed-by "nix" }` says the Nix projection, not st2, is the writer of these bytes: an
-/// edit made behind it is silently reverted on the next activation, which is why unasserted
-/// authoring refuses (R25, decision 0003). Only that marker refuses; the others are labels on
-/// declarations st2's own verbs are expected to edit.
+/// edit made behind it is silently reverted on the next activation, which is why an unasserted
+/// rewrite refuses (R25, decision 0003). Only that marker refuses; the others are labels on
+/// declarations st2's own verbs and publishers are expected to rewrite.
 ///
 /// The generator itself is the one writer that legitimately authors the declaration, and
 /// `--managed-by` is how it says so. An assertion is admitted only when it names exactly the one
 /// marker the declaration carries — a caller wrong about who owns the bytes is wrong about the
 /// edit, so a mismatched marker, an unmarked declaration, and an unresolvable multi-marker
 /// declaration all fail closed. Returns whether an assertion was matched.
-fn authorize_marker(
-    target: &KdlNode,
-    expected_identity: &str,
+pub(crate) fn authorize_asserted_marker(
+    declared: &[&str],
+    subject: &str,
     path: &Path,
     asserted: Option<&str>,
 ) -> Result<bool, AuthorError> {
-    let declared = declared_markers(target);
-    match (asserted, declared.as_slice()) {
+    match (asserted, declared) {
         (None, _) if !declared.contains(&"nix") => Ok(false),
         (None, _) => Err(AuthorError::new(
             "nix-managed-declaration",
             format!(
-                "agent {expected_identity:?} is Nix-owned; edit its Nix source instead of {}, or pass --managed-by \"nix\" if you are that projection",
+                "agent {subject:?} is Nix-owned; edit its Nix source instead of {}, or pass --managed-by \"nix\" if you are that projection",
                 path.display()
             ),
         )),
         (Some(asserted), [marker]) if *marker == asserted => Ok(true),
         (Some(asserted), []) => Err(AuthorError::new(
             "managed-by-unmarked",
             format!(
-                "--managed-by {asserted:?} claims agent {expected_identity:?}, whose declaration {} carries no `meta {{ managed-by }}` marker",
+                "--managed-by {asserted:?} claims agent {subject:?}, whose declaration {} carries no `meta {{ managed-by }}` marker",
                 path.display()
             ),
         )),
         (Some(asserted), markers) => Err(AuthorError::new(
             "managed-by-mismatch",
             format!(
-                "--managed-by {asserted:?} does not own agent {expected_identity:?}: {} declares owner {}",
+                "--managed-by {asserted:?} does not own agent {subject:?}: {} declares owner {}",
                 path.display(),
                 markers
                     .iter()
@@ -2107,6 +2143,16 @@ fn authorize_marker(
     }
 }
 
+/// The lifecycle verb's marker authority, read from the exact declaration node it edits.
+fn authorize_marker(
+    target: &KdlNode,
+    expected_identity: &str,
+    path: &Path,
+    asserted: Option<&str>,
+) -> Result<bool, AuthorError> {
+    authorize_asserted_marker(&declared_markers(target), expected_identity, path, asserted)
+}
+
 fn presentation_edit(
     text: &str,
     target: &KdlNode,