key run's liveness on the DECLARATION's host, as reconcile does

`buildDeclaration` always populates `host` (`--host` ?? this machine), so
keying liveness on the args-built agent file computed a this-machine bus id
for an agent declared `host = otherbox` — whose catalog file is present
locally via fabric sync. `convoy run --identity <that agent>` would find
nothing live and launch a DUPLICATE alongside the real session.

That falsified the property this design rests on: `run` and `up` must agree
on what "already running" means. `up` reconciles on `entry.af.host ?? thisHost`
— the declaration's host — so `run` now reads the existing declaration BEFORE
computing the bus id and keys off it.

The choice is a named, exported function (`livenessAgentFile`) rather than an
inline `??`: it is the single point where the two verbs agree or diverge, so
it deserves to be visible and directly testable. Reverting it to return the
args-built file turns two tests red.

Also, while reading the existing declaration up front:
  · reuse it for `effective` instead of re-reading the file
  · warn when a positional ROLE differs from the declared one — the role is not
    a flag, so `passedDeclarationFlags` could not see it and it was silently
    dropped on resume
  · print `session:` / `bus:` ids, so a declaration owned by another host is
    visible before anything launches

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014ePNMmLYa7qVT3h7bRCWUJ
agent-session-id: 0abcedc7-6b71-4046-9e7c-f645268c0b15
agent-tool: Claude Code
agent-tool-version: 2.1.215
agent-model: claude-opus-4-8
agent-runtime-profile: /nix/store/acr8a3l2v366jgmwiq8xdrhgz1py0db5-coding-agent-runtime-profile/share/coding-agents/profile.json
agent-skills-manifest: /nix/store/sj1v5j91h8v8d1w9lca4040302lwrd6v-agent-skills-corpus/share/agent-skills/manifest.json
tooling-profile: dotfiles@unknown-dirty

Author: schickling-assistant

src/commands.ts

@@ -30,7 +30,7 @@ import { runFullOrgSuite, runReadinessSuite } from "./doctor/suite.ts";
 import { structureChecks } from "./doctor/structure.ts";
 import { baseFile, ensureInstalled, personasDir, personasInstalled } from "./personas.ts";
 import { ROLES, parseRole } from "./role.ts";
-import { declaredRunNotice, liveForceRefusal, passedDeclarationFlags, resolveRunAction, staleFlagsNote } from "./run.ts";
+import { declaredRunNotice, liveForceRefusal, livenessAgentFile, passedDeclarationFlags, resolveRunAction, staleFlagsNote } from "./run.ts";
 import { busAgentId, isValidModel, preflight, resolvedPersonaPath, sessionId, shortHostname, type AgentSpec, type Transport } from "./agent-spec.ts";
 import { HARNESSES, HARNESS_SESSION_KEYS, HARNESS_SUFFIX_RE, harnessDescriptor, harnessesInPtyToml, harnessLimitations, isHarness, type Harness } from "./harness.ts";
 import { claudeConfigPath, codexConfigPath, pretrustDirs, pretrustDirsCodex } from "./trust.ts";
@@ -972,7 +972,24 @@ export async function cmdRun(args: string[]): Promise<number> {
   // `busIdOf`), so `run` and `up` can never disagree about what "already running" means. The gone-but-pid-
   // alive tolerance is reconcile's too: pty can transiently report `gone` under load, and treating that as
   // dead would relaunch a live agent.
-  const busId = agentBusId(af, shortHostname());
+  // Read the EXISTING declaration first, because liveness must be keyed off it, not off this invocation's
+  // flags. `buildDeclaration` always sets `af.host` (`--host` ?? this machine), whereas reconcile keys on
+  // `entry.af.host ?? thisHost` — the DECLARATION's host. Keying on the args host would mean that for an
+  // agent declared `host = dev4`, a `convoy run --identity <id>` on another box (its catalog file is present
+  // via fabric sync) computes the wrong bus id, sees nothing live, and launches a duplicate. That would
+  // falsify the exact property this design rests on: `run` and `up` must agree on what "already running"
+  // means. Deriving both from the same source makes them agree by construction.
+  let existingAf: AgentFile | null = null;
+  if (existed) {
+    try {
+      existingAf = readAgentFile(path);
+    } catch (e) {
+      err(`agent "${identity}" is declared at ${path} but its agent file could not be read: ${e instanceof Error ? e.message : String(e)}`);
+      return 1;
+    }
+  }
+
+  const busId = agentBusId(livenessAgentFile(existingAf, af), shortHostname());
   const live = (await new PtyHost(network).sessions()).filter(
     (s) => busIdOf(s) === busId && (!gone(s) || processAlive(s.pid)),
   );
@@ -987,15 +1004,14 @@ export async function cmdRun(args: string[]): Promise<number> {
   // exists, and silently re-declaring from this invocation's flags would let a stray `--model` mutate a
   // synced, fleet-visible agent file as a side effect of attaching to it.
   const reuseExisting = action === "resume" || action === "attach";
-  let effective = af;
+  const effective = reuseExisting && existingAf ? existingAf : af;
   if (reuseExisting) {
-    try {
-      effective = readAgentFile(path);
-    } catch (e) {
-      err(`agent "${identity}" is declared at ${path} but its agent file could not be read: ${e instanceof Error ? e.message : String(e)}`);
-      return 1;
-    }
-    const note = staleFlagsNote(identity, passedDeclarationFlags(args));
+    // The role is a POSITIONAL, not a flag, so `passedDeclarationFlags` cannot see it — report it
+    // separately rather than silently resuming `cos` as its declared role when the caller typed another.
+    const declaredRole = existingAf?.role;
+    const askedRole = positionals(args)[0];
+    const roleDiffers = askedRole !== undefined && declaredRole !== undefined && parseRole(askedRole) !== declaredRole;
+    const note = staleFlagsNote(identity, [...(roleDiffers ? [`role "${askedRole}"`] : []), ...passedDeclarationFlags(args)]);
     if (note) out(note);
   }
 
@@ -1005,6 +1021,9 @@ export async function cmdRun(args: string[]): Promise<number> {
 
   out(`convoy run — ${identity} (${effective.harness ?? "claude"}, ${effective.role})`);
   out(`workspace: ${effective.workspace ?? "(none)"}`);
+  // Print the host-prefixed ids: they are what `convoy up`, `pty attach`, and `st` all key on, and showing
+  // them makes an unexpected host (a declaration owned by another box) visible before anything launches.
+  out(`session: ${ref} · bus: ${busAgentId(spec)}`);
 
   if (action === "attach") {
     out(`  already running (${live.map((s) => s.name).join(", ")}) — attaching, NOT restarting it.`);

src/run.test.ts

@@ -1,11 +1,12 @@
 import { describe, it, expect } from "vitest";
 import { spawnSync } from "node:child_process";
 import { mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { hostname, tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { COMMANDS } from "./command-table.ts";
-import { declaredRunNotice, liveForceRefusal, passedDeclarationFlags, resolveRunAction, staleFlagsNote } from "./run.ts";
+import { declaredRunNotice, liveForceRefusal, livenessAgentFile, passedDeclarationFlags, resolveRunAction, staleFlagsNote } from "./run.ts";
+import { agentBusId } from "./reconcile.ts";
 
 const root = dirname(dirname(fileURLToPath(import.meta.url)));
 const bin = join(root, "bin", "convoy");
@@ -93,6 +94,29 @@ describe("passedDeclarationFlags — distinguishes declaration flags from per-in
   });
 });
 
+describe("livenessAgentFile — the single point where `run` agrees with `up` about what is running", () => {
+  const declared = { identity: "x", role: "worker" as const, host: "otherbox" };
+  const fromArgs = { identity: "x", role: "worker" as const, host: "thisbox" };
+
+  it("ACCEPTANCE: keys on the EXISTING declaration — `up` reconciles on `af.host`, so `run` must too", () => {
+    // `buildDeclaration` ALWAYS populates host (--host ?? this machine), so keying on the args-built file
+    // computes a this-machine bus id for an agent declared `host = otherbox` (catalog file arrived via
+    // fabric sync). run would find nothing live and launch a DUPLICATE beside the real one.
+    expect(livenessAgentFile(declared, fromArgs)).toBe(declared);
+    expect(livenessAgentFile(declared, fromArgs).host).toBe("otherbox");
+  });
+
+  it("falls back to the args-built file only when nothing is declared yet (the first-run path)", () => {
+    expect(livenessAgentFile(null, fromArgs)).toBe(fromArgs);
+  });
+
+  it("keys identically to reconcile's agentBusId for an explicitly-hosted agent", () => {
+    const thisHost = "thisbox";
+    expect(agentBusId(livenessAgentFile(declared, fromArgs), thisHost)).toBe(agentBusId(declared, thisHost));
+    expect(agentBusId(livenessAgentFile(declared, fromArgs), thisHost)).toBe("otherbox.x");
+  });
+});
+
 describe("declaredRunNotice — states the guarantees, the exact inverse of #92's disclaimer", () => {
   it("ACCEPTANCE: says detaching leaves the agent RUNNING (a pty session outlives its client)", () => {
     const n = declaredRunNotice("fodfix", "dev3.fodfix", "dev3.fodfix");
@@ -225,6 +249,22 @@ describe("`convoy run` end to end", () => {
     }
   });
 
+  it("resolves an explicitly-hosted declaration to ITS host, not this machine's", () => {
+    const h = setup();
+    try {
+      const catalog = catalogOf(h);
+      mkdirSync(catalog, { recursive: true });
+      writeFileSync(join(catalog, "elsewhere.toml"), 'identity = "elsewhere"\nrole = "worker"\nhost = "otherbox"\nworkspace = "' + h + '"\n');
+      // No --host passed: the declaration's host must still win for the session ref and the bus id.
+      const r = cli(["run", "--identity", "elsewhere", "--dry-run", "--no-attach"], h);
+      expect(r.rc).toBe(0);
+      expect(r.out).toContain("otherbox.elsewhere");
+      expect(r.out).not.toContain(`${hostname().split(".")[0]?.toLowerCase()}.elsewhere`);
+    } finally {
+      teardown();
+    }
+  });
+
   it("accepts --permanent, which #92 rejected (rc=2) as a contradiction for an undeclared session", () => {
     const h = setup();
     try {

src/run.ts

@@ -111,6 +111,21 @@ export function passedDeclarationFlags(args: readonly string[]): string[] {
   return DECLARATION_FLAGS.filter((f) => args.includes(f));
 }
 
+/** Which agent file `run` must key LIVENESS on: the existing declaration whenever there is one, never the
+ *  one just built from this invocation's flags.
+ *
+ *  This is the single point where `run` either does or does not agree with `convoy up` about what "already
+ *  running" means, so it is a named function rather than an inline `??` — the coherence claim of this whole
+ *  design reduces to this choice.
+ *
+ *  `up`'s reconcile keys on `entry.af.host ?? thisHost` — the DECLARATION's host. `buildDeclaration` always
+ *  populates `host` (`--host` ?? this machine), so keying on the args-built file would compute a
+ *  this-machine-prefixed bus id for an agent declared `host = otherbox` (its catalog file having arrived by
+ *  fabric sync). `run` would then find nothing live and launch a DUPLICATE alongside the real one. */
+export function livenessAgentFile<T>(existing: T | null, fromArgs: T): T {
+  return existing ?? fromArgs;
+}
+
 /** The line `run` prints once the session is up, stating the guarantees it DOES have — the exact inverse
  *  of #92's `adHocNotice`, which existed to disclaim them. Detaching is safe and is worth saying: a pty
  *  session outlives its client, and because the agent is declared, `convoy up` also respawns it if the