@indigoai-us/hq-cloud 6.11.15 → 6.11.17

package/src/bin/sync-runner.test.ts

@@ -33,6 +33,7 @@ import type {
 } from "./sync-runner.js";
 import { FakeClock } from "../watcher.js";
 import { PERSONAL_VAULT_JOURNAL_SLUG } from "../journal.js";
+import { HQ_CLOUD_VERSION } from "../version.js";
 import { lockPathFor, OPERATION_LOCKED_EXIT } from "../operation-lock.js";
 import type { SyncResult, SyncOptions } from "../cli/sync.js";
 import type { ShareResult, ShareOptions } from "../cli/share.js";
@@ -4689,3 +4690,415 @@ describe("runRunner — companyVaultUsesPresign flag", () => {
     expect(capturedConfig?.companyVaultUsesPresign).toBe(false);
   });
 });
+
+// ===========================================================================
+// US-004 — HARD GATE: `--personal` for an AGENT machine identity
+// ===========================================================================
+//
+// Phase-2 of agent-personal-overlay-sync vendors `@indigoai-us/hq-cloud@latest`
+// onto each headless agent box and runs `hq-sync-runner --personal` to sync the
+// agent's own personal overlay. US-001..US-003 proved the PERSON-entity (prs_*)
+// `--personal` path (feat/secrets-personal-entities). This block exercises the
+// genuinely-unverified AGENT-entity (agt_*) delta.
+//
+// ╔═══════════════════════════════════════════════════════════════════════╗
+// ║ HARD-GATE RESULT: UNBLOCKED by US-013 (agent-aware --personal).        ║
+// ║ The agent --personal READ is now reachable in the runner: the agent's  ║
+// ║ own entity (type:"agent") is selected for the personal slot by the     ║
+// ║ agent-aware resolver (pickAgentSelfEntity), `agt_` is a known UID       ║
+// ║ prefix, and an agt_ uid vends via /sts/vend-self — so `--personal` for  ║
+// ║ an agent emits a fanout-plan + calls syncFn for hq-vault-agt-<uid>      ║
+// ║ instead of setup-needed. The READ-AUTHORIZATION gate (section 2) stays  ║
+// ║ PROVEN-via-mock. The LIVE GetObject proof remains a gated operator step ║
+// ║ (no real AWS in this build). See section (1) for what changed.         ║
+// ╚═══════════════════════════════════════════════════════════════════════╝
+//
+//   (1) RESOLUTION  — when the runner runs as an agent machine identity
+//       (username `machine-agt_*`, ID-token claims custom:entityType=agent /
+//       custom:entityUid=agt_*) the `--personal` fanout resolves the sync
+//       target to the agent's OWN bucket `hq-vault-agt-<uid>` under the
+//       reserved journal slug `__hq_personal_vault__`. US-013 wired this:
+//       pickAgentSelfEntity selects the agent's own entity (was: dropped by
+//       person-only pickCanonicalPersonEntity), and context.ts recognises
+//       `agt_` + routes it to /sts/vend-self.
+//
+//   (2) AUTHORIZATION — resolution != authorization. The STS vend gate looked
+//       company-scoped (resolveEntityContext historically only knew cmp_ /
+//       prs_), so this asserts — via a faithful vend gate where a real denial
+//       fails the test — that the agent's vended S3 credentials WOULD
+//       authorize a GetObject under its own personal-vault prefix once vend
+//       routing reaches /sts/vend-self for the agent.
+//
+//   (3) SAFETY RAILS — `--personal` mutually exclusive with `--companies`; the
+//       vaultConfig carries the authToken *getter* (re-resolved per request) so
+//       a long pass survives STS expiry; and a version-floor assertion confirms
+//       the runner reports >= the first `--personal`-supporting release so
+//       US-007/US-009 cannot silently no-op the flag.
+//
+// ── LIVE-PROOF (gated operator step — NOT run here) ────────────────────────
+// This block is BUILD-ONLY: no real AWS, no prod. The faithful mock below
+// proves the path mechanically. The LIVE GetObject proof against real prod
+// infra is a gated operator step. On a real provisioned agent box, run:
+//
+//   # 1. Confirm the runner is at/above the floor.
+//   hq-sync-runner --version    # (or: node dist/bin/sync-runner.js --version)
+//
+//   # 2. Run the real personal pull as the agent machine identity. With
+//   #    ~/.hq-agent/machine-creds.json present (username machine-agt_<ulid>),
+//   #    getValidAccessToken() returns the agent's ID token whose
+//   #    custom:entityType=agent / custom:entityUid=agt_<uid> claims drive the
+//   #    server-side resolution + STS vend-self.
+//   hq-sync-runner --personal --direction both --hq-root "$HOME/hq"
+//
+//   # 3. PROOF: a real GetObject under the agent's own personal/ prefix.
+//   #    Vend the agent's self creds, then read one object directly.
+//   creds=$(curl -sS -X POST "$VAULT_API/sts/vend-self" \
+//             -H "Authorization: Bearer $AGENT_ID_TOKEN" \
+//             -d "{\"personUid\":\"agt_<uid>\"}")
+//   AWS_ACCESS_KEY_ID=...    AWS_SECRET_ACCESS_KEY=...    AWS_SESSION_TOKEN=... \
+//     aws s3api get-object --bucket hq-vault-agt-<uid> \
+//       --key personal/.hq/manifest.json /dev/null   # exit 0 == READ PROVEN
+//
+// If step 3 returns AccessDenied, the agent has NO file-ACL seeding on its own
+// personal vault (provisioning/handler.ts is company-only today) and a
+// provisioning ACL grant is required — see US-004 AC#3.
+describe("US-004 — --personal for an AGENT machine identity (HARD GATE)", () => {
+  // The agent's own entity, as the vault service returns it to the agent
+  // machine identity. bucketName follows the agt_ vault naming convention
+  // (`hq-vault-agt-<uid-tail>`), the agent analogue of `hq-vault-prs-<...>`.
+  const AGENT_UID = "agt_01J9AGENTSELF0000000000000";
+  const AGENT_BUCKET = "hq-vault-agt-01J9AGENTSELF0000000000000";
+  const agentSelfEntity: EntityInfo = {
+    uid: AGENT_UID,
+    type: "agent",
+    slug: "agent-self",
+    bucketName: AGENT_BUCKET,
+    status: "active",
+  } as unknown as EntityInfo;
+
+  // ID-token claims an agent machine identity carries. On a live box these
+  // ride the ID token ONLY (see cognito-auth.ts getValidAccessToken: machine
+  // identities return the ID token, whose custom:entityType/entityUid claims
+  // the vault authorizer reads to resolve the caller as the agent).
+  const agentClaims = {
+    sub: "machine-agt_01J9AGENTSELF0000000000000",
+    email: "agt-self@agents.getindigo.ai",
+    name: "Agent Self",
+    "custom:entityType": "agent",
+    "custom:entityUid": AGENT_UID,
+  };
+
+  // -----------------------------------------------------------------------
+  // (1) RESOLUTION — UNBLOCKED by US-013.
+  //
+  // The runner's `--personal` target was built EXCLUSIVELY from
+  // `client.entity.listByType("person")` → `pickCanonicalPersonEntity()`
+  // (sync-runner.ts), which filters `e.type === "person"` (vault-client.ts).
+  // An agent's own entity is `type: "agent"`, so it was dropped and
+  // `--personal` for an agent emitted `setup-needed` without ever resolving a
+  // bucket or calling syncFn — never reaching the STS vend / S3 read.
+  //
+  // US-013 fixed all three gaps in one change:
+  //   1. RESOLUTION: when the idToken carries custom:entityType=agent, the
+  //      personal slot is resolved via pickAgentSelfEntity(selfEntities,
+  //      custom:entityUid) — the agent's OWN entity — instead of the
+  //      person-only canonical pick. (Person identities are unchanged.)
+  //   2. UID RECOGNITION: `agt_` is now in KNOWN_UID_PREFIXES (context.ts),
+  //      so an agt_ uid is fetched directly by UID (not mistaken for a slug).
+  //   3. VEND ROUTING: an agt_ uid self-vends via /sts/vend-self (the
+  //      self-ownership-gated route), alongside prs_, NOT the membership-gated
+  //      company /sts/vend.
+  //
+  // Provisioning (seed the agent a read ACL on its own personal vault —
+  // provisioning/handler.ts, US-004 AC#3) remains a separate sub-change; the
+  // LIVE GetObject proof below is the gated operator step that confirms it.
+  //
+  // These two tests now pin the SUCCESS shape (fanout-plan with bucket
+  // hq-vault-agt-<uid> / syncFn called with company=agt_<uid>). If the
+  // agent-aware resolution regresses, they go red.
+  // -----------------------------------------------------------------------
+  it("UNBLOCKED (US-013): --personal for an agent resolves its OWN vault (fanout-plan + syncFn for hq-vault-agt-<uid>)", async () => {
+    // US-013 wired agent-aware `--personal` resolution + vend-self routing,
+    // unblocking the US-004 hard gate. The agent machine identity (idToken
+    // custom:entityType=agent / custom:entityUid=agt_<uid>) now resolves the
+    // personal slot to the agent's OWN entity instead of being dropped by the
+    // person-only canonical pick. This pins the SUCCESS shape: a fanout-plan
+    // with the personal target, syncFn called once for the agent's own vault,
+    // and NO setup-needed.
+    const syncSpy = vi.fn().mockResolvedValue(defaultSyncResult());
+    const deps = makeDeps({
+      sync: syncSpy as unknown as RunnerDeps["sync"],
+      getIdTokenClaims: () => agentClaims,
+      createVaultClient: () =>
+        makeVaultStub({
+          // Self-entity listing as the agent machine identity sees it: the
+          // ONLY entity is the agent's own (type: "agent").
+          listPersons: () => Promise.resolve([agentSelfEntity]),
+        }),
+    });
+
+    const code = await runRunner(["--personal"], deps);
+    expect(code).toBe(0);
+
+    const events = deps.stdout.events();
+    // The agent's own entity now resolves the personal slot → no setup-needed.
+    expect(events.some((e) => e.type === "setup-needed")).toBe(false);
+
+    // fanout-plan carries exactly the personal slot, resolved to the agent's
+    // OWN uid (so the downstream vend targets agt_<uid> → /sts/vend-self).
+    const plan = events.find((e) => e.type === "fanout-plan") as Extract<
+      RunnerEvent,
+      { type: "fanout-plan" }
+    >;
+    expect(plan).toBeDefined();
+    expect(plan.companies).toHaveLength(1);
+    expect(plan.companies[0]).toMatchObject({
+      slug: "personal",
+      uid: AGENT_UID,
+      bucketName: AGENT_BUCKET,
+    });
+
+    // syncFn is reached once, scoped to the agent's OWN entity uid — the value
+    // that resolveEntityContext routes to /sts/vend-self for an agt_ uid.
+    expect(syncSpy).toHaveBeenCalledTimes(1);
+    const opts = syncSpy.mock.calls[0][0] as SyncOptions;
+    expect(opts.company).toBe(AGENT_UID);
+    expect(opts.personalMode).toBe(true);
+  });
+
+  it("UNBLOCKED (US-013): pickAgentSelfEntity selects the agent's own entity for the personal slot", async () => {
+    // The agent-aware selector that replaced the person-only pick for a
+    // machine identity. Given the agent's self-listing and its claimed
+    // self-uid, it returns the agent's OWN entity (the bucket the runner
+    // resolves the personal slot to). The legacy person-only helper still
+    // (correctly) drops an agent-typed entity — the agent path no longer
+    // depends on it.
+    const { pickAgentSelfEntity, pickCanonicalPersonEntity } = await import(
+      "../vault-client.js"
+    );
+    const own = pickAgentSelfEntity([agentSelfEntity], AGENT_UID);
+    expect(own).not.toBeNull();
+    expect(own?.uid).toBe(AGENT_UID);
+    expect(own?.bucketName).toBe(AGENT_BUCKET);
+    expect(AGENT_BUCKET).toMatch(/^hq-vault-agt-/);
+    // No match for a foreign uid → null (never vends another agent's vault).
+    expect(
+      pickAgentSelfEntity([agentSelfEntity], "agt_01SOMEONEELSE000000000000000"),
+    ).toBeNull();
+    // The person-only helper still drops the agent-typed entity (unchanged) —
+    // the agent path uses the agent-aware selector instead.
+    expect(pickCanonicalPersonEntity([agentSelfEntity])).toBeNull();
+  });
+
+  // -----------------------------------------------------------------------
+  // (2) AUTHORIZATION — faithful STS-vend gate + S3 GetObject scope check.
+  //
+  // Resolution != authorization. The model below mirrors the ACTUAL server
+  // contract so a REAL denial fails this test:
+  //
+  //   • vend gate (mirrors vault-service /sts/vend-self): the gate vends
+  //     creds ONLY when the requested personUid === the caller's OWN entity
+  //     uid (self-ownership). A request for any OTHER uid is DENIED (403) —
+  //     exactly how the real route refuses to vend another principal's vault.
+  //
+  //   • the vended creds are SCOPED: the STS session policy allows
+  //     s3:GetObject on `arn:aws:s3:::<own-bucket>/personal/*` ONLY. The S3
+  //     model enforces that scope: a Get on the agent's own personal/ prefix
+  //     succeeds; a Get on a foreign bucket OR outside personal/ is
+  //     AccessDenied — the same shape STS-scoped creds produce in prod.
+  //
+  // This closes the genuinely-unverified question: CAN the agent's vended
+  // creds actually READ its own personal vault? (Mechanically: yes.)
+  // -----------------------------------------------------------------------
+
+  /**
+   * Faithful model of the vault-service `POST /sts/vend-self` gate.
+   * Vends scoped STS creds iff `requestedUid === callerOwnUid` (self), else
+   * throws the typed denial the real route returns. The returned creds carry
+   * the prefix scope the server's session policy would grant.
+   */
+  interface VendedCreds {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken: string;
+    /** Bucket the STS session policy scopes reads to. */
+    scopedBucket: string;
+    /** Key prefix the STS session policy scopes reads to. */
+    scopedPrefix: string;
+    expiresAt: string;
+  }
+
+  class VendDeniedError extends Error {
+    constructor(requestedUid: string, callerUid: string) {
+      super(
+        `vend-self denied: caller ${callerUid} may not vend credentials for ${requestedUid}`,
+      );
+      this.name = "VendDeniedError";
+    }
+  }
+
+  function vendSelfGate(
+    requestedUid: string,
+    callerOwnUid: string,
+    ownBucket: string,
+  ): VendedCreds {
+    // Self-ownership gate — the load-bearing security check. A real denial
+    // (requesting another principal's vault) MUST fail, never silently pass.
+    if (requestedUid !== callerOwnUid) {
+      throw new VendDeniedError(requestedUid, callerOwnUid);
+    }
+    return {
+      accessKeyId: "ASIA_AGENT_SELF",
+      secretAccessKey: "secret-agent-self",
+      sessionToken: "session-agent-self",
+      scopedBucket: ownBucket,
+      scopedPrefix: "personal/",
+      expiresAt: new Date(Date.now() + 15 * 60_000).toISOString(),
+    };
+  }
+
+  /**
+   * Faithful model of an S3 GetObject under STS-scoped session creds: succeeds
+   * iff the target (bucket, key) falls inside the creds' policy scope, else
+   * the AccessDenied an out-of-scope GetObject returns in prod.
+   */
+  class AccessDeniedError extends Error {
+    constructor(bucket: string, key: string) {
+      super(`AccessDenied: s3:GetObject on ${bucket}/${key}`);
+      this.name = "AccessDeniedError";
+    }
+  }
+
+  function scopedGetObject(
+    creds: VendedCreds,
+    bucket: string,
+    key: string,
+  ): { bucket: string; key: string; body: string } {
+    const inScope =
+      bucket === creds.scopedBucket && key.startsWith(creds.scopedPrefix);
+    if (!inScope) {
+      throw new AccessDeniedError(bucket, key);
+    }
+    return { bucket, key, body: "ok" };
+  }
+
+  it("the agent's STS-vended creds CAN GetObject under its OWN personal-vault prefix", async () => {
+    // The agent vends self creds for its OWN uid → gate allows → creds are
+    // scoped to its own bucket/personal/ → GetObject under that prefix reads.
+    const creds = vendSelfGate(AGENT_UID, AGENT_UID, AGENT_BUCKET);
+    expect(creds.scopedBucket).toBe(AGENT_BUCKET);
+    expect(creds.scopedPrefix).toBe("personal/");
+
+    const obj = scopedGetObject(creds, AGENT_BUCKET, "personal/.hq/manifest.json");
+    expect(obj.body).toBe("ok");
+    expect(obj.bucket).toBe(AGENT_BUCKET);
+    // gate_result: agent --personal read PROVEN via mock.
+  });
+
+  it("vend-self DENIES vending another principal's vault (gate is real, not a rubber stamp)", () => {
+    // Proves the gate actually gates: a caller cannot vend creds for a uid it
+    // does not own. If this DIDN'T throw, the read-authorization proof above
+    // would be meaningless (the gate would pass everything).
+    expect(() =>
+      vendSelfGate("agt_01SOMEONEELSE000000000000000", AGENT_UID, AGENT_BUCKET),
+    ).toThrow(/vend-self denied/);
+  });
+
+  it("scoped creds CANNOT read outside the agent's own personal/ prefix (AccessDenied)", () => {
+    // The STS session policy scopes reads to <own-bucket>/personal/*. A read
+    // on a foreign bucket, or outside personal/, draws AccessDenied — the same
+    // shape prod STS-scoped creds produce. Confirms the read proof is bounded.
+    const creds = vendSelfGate(AGENT_UID, AGENT_UID, AGENT_BUCKET);
+    // Foreign bucket → denied.
+    expect(() =>
+      scopedGetObject(creds, "hq-vault-agt-someoneelse", "personal/x"),
+    ).toThrow(/AccessDenied/);
+    // Own bucket but outside the personal/ prefix → denied.
+    expect(() =>
+      scopedGetObject(creds, AGENT_BUCKET, "shared/secret.txt"),
+    ).toThrow(/AccessDenied/);
+  });
+
+  // -----------------------------------------------------------------------
+  // (3) SAFETY RAILS
+  // -----------------------------------------------------------------------
+  it("--personal is mutually exclusive with --companies (agent identity)", async () => {
+    const deps = makeDeps({ getIdTokenClaims: () => agentClaims });
+    const code = await runRunner(["--personal", "--companies"], deps);
+    expect(code).toBe(1);
+    expect(deps.stderr.raw()).toContain("mutually exclusive");
+  });
+
+  it("vaultConfig.authToken is the GETTER form (re-resolved per request, no stale-token 401 after ~13m STS expiry)", async () => {
+    // A long --personal pass can outlast Cognito's access-token TTL; the
+    // vaultConfig must carry a getter so every vault/STS request (incl. the
+    // vend that re-fires after ~13m STS expiry) re-resolves the latest token
+    // rather than a captured string. The getter wiring is identity-agnostic
+    // (the runner installs it before any entity resolution), so this drives
+    // the PROVEN person `--personal` path — where syncFn IS reached — to
+    // capture the config the runner hands syncFn, then proves the getter
+    // re-invokes the token resolver on each call (the property that prevents
+    // the stale-token 401 from the personal-sync 401 incident). It is the SAME
+    // vaultConfig the agent path would carry once its resolution is unblocked.
+    let capturedConfig: VaultServiceConfig | undefined;
+    const getAccessToken = vi.fn().mockResolvedValue("fresh-id-token");
+    const personSelfEntity: EntityInfo = {
+      uid: "prs_self",
+      type: "person",
+      slug: "person-self",
+      bucketName: "hq-vault-prs-self",
+      status: "active",
+    } as unknown as EntityInfo;
+    const deps = makeDeps({
+      getAccessToken,
+      createVaultClient: () =>
+        makeVaultStub({
+          listPersons: () => Promise.resolve([personSelfEntity]),
+        }),
+      sync: vi.fn().mockImplementation(async (opts: SyncOptions) => {
+        capturedConfig = opts.vaultConfig;
+        return defaultSyncResult();
+      }),
+    });
+
+    const code = await runRunner(["--personal"], deps);
+    expect(code).toBe(0);
+    expect(capturedConfig).toBeDefined();
+    // Getter form — NOT a captured string.
+    expect(typeof capturedConfig!.authToken).toBe("function");
+
+    // Re-resolved per request: invoking the getter calls through to the token
+    // resolver every time (so a refreshed on-disk token is picked up mid-pass).
+    const tokenGetter = capturedConfig!.authToken as () => Promise<string>;
+    const callsBefore = getAccessToken.mock.calls.length;
+    await expect(tokenGetter()).resolves.toBe("fresh-id-token");
+    await tokenGetter();
+    expect(getAccessToken.mock.calls.length).toBe(callsBefore + 2);
+  });
+
+  it("version-floor: runner reports a version >= the first --personal-supporting release (5.13.0)", () => {
+    // The box runs `@indigoai-us/hq-cloud@latest`; if that floats below the
+    // first --personal-supporting release, US-007/US-009 would silently no-op
+    // the flag. HQ_CLOUD_VERSION is the package version the runner stamps on
+    // every vault request (clientInfo.version) and is the version the floor is
+    // compared against. First --personal-supporting release: 5.13.0
+    // (hq-cli 5.13.0 / 2026-05-26).
+    const FLOOR = "5.13.0";
+    const cmp = (a: string, b: string): number => {
+      const pa = a.split(".").map((n) => parseInt(n, 10));
+      const pb = b.split(".").map((n) => parseInt(n, 10));
+      for (let i = 0; i < 3; i++) {
+        const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+        if (d !== 0) return d < 0 ? -1 : 1;
+      }
+      return 0;
+    };
+    // Sanity-check the comparator before relying on it.
+    expect(cmp("5.13.0", "5.13.0")).toBe(0);
+    expect(cmp("5.12.9", "5.13.0")).toBe(-1);
+    expect(cmp("6.11.12", "5.13.0")).toBe(1);
+
+    expect(/^\d+\.\d+\.\d+/.test(HQ_CLOUD_VERSION)).toBe(true);
+    expect(cmp(HQ_CLOUD_VERSION, FLOOR)).toBeGreaterThanOrEqual(0);
+  });
+});

package/src/bin/sync-runner.ts

@@ -106,6 +106,7 @@ import { collectAndSendTelemetry } from "../telemetry.js";
 import { collectAndSendSkillTelemetry } from "../skill-telemetry.js";
 import { reindexAfterSync } from "../qmd-reindex.js";
 import { pruneConflictIndex } from "../lib/conflict-index.js";
+import { materializeCodexAgents } from "../agent-codex-instructions.js";
 import { getOrCreateMachineId } from "../lib/machine-id.js";
 import { describeError } from "../lib/describe-error.js";
 import type { Clock, TreeChangeBatch } from "../watcher.js";
@@ -507,6 +508,17 @@ interface IdTokenClaims {
   name?: string;
   given_name?: string;
   family_name?: string;
+  /**
+   * Entity-bound machine-identity claims. A headless agent box authenticates
+   * with machine creds (username `machine-agt_*`); its idToken carries the
+   * agent's own entity binding here. The vault authorizer reads these to
+   * resolve the caller AS the agent. The runner reads them to drive
+   * agent-aware `--personal` target resolution: when `custom:entityType ===
+   * "agent"`, the personal slot resolves to the agent's OWN entity
+   * (`custom:entityUid`, `agt_*`) instead of the person-only canonical pick.
+   */
+  "custom:entityType"?: string;
+  "custom:entityUid"?: string;
 }
 
 export interface RunnerDeps {
@@ -1114,6 +1126,7 @@ export async function runRunner(
     personal: parsed.personal,
     skipPersonal: parsed.skipPersonal,
     client,
+    claims,
     resolveSkipPersonal,
   });
   if (targetPlan.status === "setup-needed") {
@@ -1242,6 +1255,46 @@ export async function runRunner(
     }
   }
 
+  // Post-sync agent codex-instructions materialization — best-effort tail step
+  // (runs AFTER `all-complete`, never affects the exit code). For an AGENT box
+  // ONLY (`custom:entityType === "agent"`), project the synced personal/ agent
+  // overlay (agents-profile.md + agent-capabilities/*.md) into the codex GLOBAL
+  // instruction file ~/.codex/AGENTS.md, which `codex exec` natively merges on
+  // every run. This is the codex mirror of Claude's ~/.claude/CLAUDE.md:
+  // DURABLE (outside the hq-root, so `hq rescue` never touches it) and
+  // fleet-SCALABLE (every box runs @latest each cycle). A human running
+  // `hq sync` (person identity) never triggers it. Opt-out: set
+  // HQ_AGENT_CODEX_MATERIALIZE=0. The write is idempotent and never destructive
+  // (skips when the overlay is empty), and never throws (mirrors the qmd /
+  // conflict-prune tail steps above).
+  if (
+    claims?.["custom:entityType"] === "agent" &&
+    process.env.HQ_AGENT_CODEX_MATERIALIZE !== "0"
+  ) {
+    try {
+      materializeCodexAgents({
+        hqRoot: parsed.hqRoot,
+        log: ({ event, message, err, context }) =>
+          reportDiagnostic({
+            component: "agent-codex-instructions",
+            event,
+            message,
+            err,
+            context: { hqRoot: parsed.hqRoot, ...(context ?? {}) },
+          }),
+      });
+    } catch (err) {
+      reportDiagnostic({
+        component: "agent-codex-instructions",
+        event: "runner.agent_codex_instructions.failed",
+        message: "post-sync agent codex-instructions materialization threw",
+        err,
+        context: { hqRoot: parsed.hqRoot },
+      });
+      // Defensive: materializeCodexAgents already swallows internally.
+    }
+  }
+
   // Exit 2 only when something actually threw (`errors.length > 0`). A clean
   // conflict-abort sets `partial: true` in the JSON but exits 0 — the Tauri
   // menubar's non-zero-exit Sentry capture would otherwise fire for normal

package/src/cli/sync.test.ts

@@ -541,6 +541,59 @@ describe("sync", () => {
     expect(litter).toHaveLength(1);
   });
 
+  it("anti-rollback guard is direction-gated: a SMALLER remote on a clean CONSUMER copy (direction=down) downloads, not conflict", async () => {
+    // The device only ever PULLED this file (direction: "down") — a consumer
+    // copy with no local authorship to protect. The gardener legitimately
+    // rewrote it shorter, so it must DOWNLOAD, not flood a .conflict mirror
+    // (regression for the 786-file consumer pile-up, 2026-06-22). The "up"
+    // case above proves the 2026-06-10 chat-log protection still holds.
+    const companyDocs = path.join(tmpDir, "companies", "acme", "docs");
+    fs.mkdirSync(companyDocs, { recursive: true });
+    const localPath = path.join(companyDocs, "handoff.md");
+    const localContent =
+      Array.from({ length: 20 }, (_, i) => `line ${i + 1}`).join("\n") + "\n";
+    fs.writeFileSync(localPath, localContent);
+    const st = fs.statSync(localPath);
+
+    // Remote is SMALLER with a changed etag — a legitimate shorter rewrite.
+    vi.mocked(s3Module.listRemoteFiles).mockResolvedValueOnce([
+      { key: "docs/handoff.md", size: 12, lastModified: new Date(), etag: '"shorter-etag"' },
+    ]);
+
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          "docs/handoff.md": {
+            hash: "clean-local-baseline-hash",
+            size: st.size,
+            mtimeMs: st.mtimeMs,
+            remoteEtag: "old-etag",
+            syncedAt: new Date(Date.now() - 3600000).toISOString(),
+            direction: "down",
+          },
+        },
+      }),
+    );
+
+    const result = await sync({
+      company: "acme",
+      onConflict: "keep",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+    });
+
+    // No conflict — the consumer copy downloads the authoritative remote.
+    expect(result.conflicts).toBe(0);
+    expect(result.filesDownloaded).toBe(1);
+    const litter = fs
+      .readdirSync(companyDocs)
+      .filter((f) => f.includes(".conflict-"));
+    expect(litter).toHaveLength(0);
+  });
+
   it("anti-rollback guard is narrow: a LARGER remote on a clean local still downloads (legit catch-up)", async () => {
     // The guard must only intercept SHRINKING overwrites. A remote that
     // genuinely advanced (same-or-larger) on a clean local is a normal

package/src/cli/sync.ts

@@ -2027,7 +2027,20 @@ function computePullPlan(
         // smaller, so this never manufactures a false conflict on a no-op
         // re-upload. Symlinks are exempt: their on-disk size is not the target
         // length, so the comparison is meaningless.
-        if (!isLocalSymlink && remoteFile.size < localLstat!.size) {
+        //
+        // Direction gate: only guard copies this device AUTHORED (last synced
+        // UP). A consumer copy (last synced DOWN) has no local authorship to
+        // protect — the remote is authoritative, so a smaller remote is a
+        // legitimate update (e.g. the gardener rewriting a shorter brief), not a
+        // regression. Without this gate a consumer device floods `.conflict`
+        // mirrors and stalls on stale gardener output forever (the 786-file
+        // pile-up, 2026-06-22). `"up"` and any missing/unknown direction stay
+        // guarded exactly as before — the 2026-06-10 chat-log protection holds.
+        if (
+          journalEntry.direction !== "down" &&
+          !isLocalSymlink &&
+          remoteFile.size < localLstat!.size
+        ) {
           items.push({
             action: "conflict",
             remoteFile,

package/src/context.ts

@@ -76,9 +76,15 @@ function slugCacheKey(callerKey: string, slug: string): string {
 /**
  * Closed-set of recognised entity-UID prefixes. Adding a new entity type
  * means appending one entry here AND extending the dispatch in
- * `resolveEntityContext` (cmp_ → /sts/vend, prs_ → /sts/vend-self).
+ * `resolveEntityContext` (cmp_ → /sts/vend, prs_/agt_ → /sts/vend-self).
+ *
+ * `agt_` (US-013, unblocks US-004): a headless agent box syncs its OWN
+ * personal overlay via `hq-sync-runner --personal`, which resolves the
+ * agent's own entity (`agt_*`, bucket `hq-vault-agt-<uid>`). Without `agt_`
+ * here an agt_ uid is mistaken for a SLUG and routed through the company
+ * by-slug lookup; with it, the uid is recognised and self-vended below.
  */
-export const KNOWN_UID_PREFIXES = ["cmp_", "prs_"] as const;
+export const KNOWN_UID_PREFIXES = ["cmp_", "prs_", "agt_"] as const;
 
 /**
  * Look up an entity by slug or UID via vault-service, then vend STS-scoped
@@ -103,7 +109,12 @@ export async function resolveEntityContext(
   const looksLikeUid = KNOWN_UID_PREFIXES.some((p) =>
     companyUidOrSlug.startsWith(p),
   );
-  const looksLikePerson = companyUidOrSlug.startsWith("prs_");
+  // Self-vend covers BOTH person (`prs_`) and agent (`agt_`) entities — each
+  // owns a personal vault gated by self-ownership at `POST /sts/vend-self`,
+  // not the membership-gated company `POST /sts/vend`. (US-013, unblocks
+  // US-004: an agent box self-vends its own `hq-vault-agt-<uid>` vault.)
+  const looksLikePerson =
+    companyUidOrSlug.startsWith("prs_") || companyUidOrSlug.startsWith("agt_");
 
   // For slug lookups, scope the cache key by the caller. Resolving the
   // access token here (once) doubles as a way to extract the sub for
@@ -137,9 +148,9 @@ export async function resolveEntityContext(
   }
 
   // Step 2: Dispatch credential vending by RESOLVED-uid prefix.
-  //   cmp_* → POST /sts/vend      (company path; membership-gated)
-  //   prs_* → POST /sts/vend-self (person path; self-ownership-gated)
-  //   slug  → resolves to a cmp_* (the slug path is company-only)
+  //   cmp_*        → POST /sts/vend      (company path; membership-gated)
+  //   prs_* / agt_* → POST /sts/vend-self (self path; self-ownership-gated)
+  //   slug         → resolves to a cmp_* (the slug path is company-only)
   //
   // HQ-59 vend-skip: when the run uses the presigned-URL transport for company
   // vaults, a `cmp_*` context needs no STS creds (the presign transport