@lanes-sh/link 0.6.5 → 0.6.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lanes-sh/link",
-  "version": "0.6.5",
+  "version": "0.6.6",
   "description": "A self-hostable MCP gateway for all your connections, memory, tasks, files, and secrets",
   "license": "Apache-2.0",
   "homepage": "https://lanes.sh/link",

package/src/cli/commands/target.ts

@@ -66,6 +66,16 @@ export interface TargetSummary {
   /** Whether a deployment is declared. Unknown, and false, for a pointer. */
   readonly deployed: boolean;
   readonly deployment: DeploymentIdentity | null;
+  /**
+   * When this target was last deployed, and which CLI release rolled it.
+   *
+   * The one part of a pointer entry that is *not* somewhere else: `deploy`
+   * writes the record on both ends, so this machine can answer "what is running
+   * up there" without following the pointer or waking the endpoint. Null means
+   * nothing has deployed this target since the field existed.
+   */
+  readonly lastDeploy: string | null;
+  readonly lastDeployVersion: string | null;
   /** Only when asked for; absent is "not asked", null is "asked, no answer". */
   readonly url?: string | null;
 }
@@ -136,6 +146,13 @@ async function survey(
 
 /** One entry, rendered without following it. */
 function summarise(name: string, entry: WorkspaceTarget, isSelected: boolean): TargetSummary {
+  // Both shapes carry it: the deploy record is written to the target's own
+  // workspace *and* to the pointer here, which is what keeps it readable offline.
+  const record = {
+    lastDeploy: entry.last_deploy ?? null,
+    lastDeployVersion: entry.last_deploy_version ?? null,
+  };
+
   if (isPointer(entry)) {
     return {
       name,
@@ -147,6 +164,7 @@ function summarise(name: string, entry: WorkspaceTarget, isSelected: boolean): T
       knowledge: null,
       deployed: false,
       deployment: null,
+      ...record,
     };
   }
 
@@ -160,6 +178,7 @@ function summarise(name: string, entry: WorkspaceTarget, isSelected: boolean): T
     knowledge: null,
     deployed: entry.deploy !== undefined,
     deployment: deploymentIdentity(entry.deploy),
+    ...record,
   };
 }
 
@@ -328,6 +347,15 @@ export async function targetShow(name: string | undefined, flags: TargetFlags):
       ['  region', summary.deployment.region],
       ...(summary.deployment.project ? [['  project', summary.deployment.project]] : []),
       ['  address', url ?? style.dim('not answering — is it deployed?')],
+      // The release that rolled it, which is the version of this CLI running up
+      // there: the image is built from the installed package. Recorded by
+      // `deploy` once the rollout succeeded, so a target deployed by an older
+      // CLI than this one says so rather than saying nothing.
+      ['  last deploy', summary.lastDeploy ?? style.dim('not recorded')],
+      [
+        '  version',
+        summary.lastDeployVersion ?? style.dim('not recorded — deploy again to record it'),
+      ],
     ]);
   });
 }

package/src/deployments/deploy.ts

@@ -1,15 +1,16 @@
 import {
   ConfigError,
-  recordTarget,
   resolveTargetWorkspace,
   resolveWorkspaceRoot,
   type DeployConfig,
 } from '#profile';
 import { announce, fail, heading, ok, print, style, warn } from '#cli/output.ts';
 import { staleNudge } from '#cli/release.ts';
+import { version } from '#cli/version.ts';
 import { confirm, isInteractive } from '#cli/prompt.ts';
 import { openSecretStoreFor, resolveProfile, type GlobalFlags } from '#cli/runtime.ts';
 import { resolveTarget, vaultEnv } from './bootstrap.ts';
+import { recordDeployment, type DeploymentRecord } from './record.ts';
 import { printSteps, runSteps } from './steps.ts';
 import { driverFor } from './drivers.ts';
 import { prepareSecrets, readableRefs, rotatableRefs } from './prepare.ts';
@@ -186,7 +187,10 @@ export async function deploy(flags: DeployFlags): Promise<void> {
     printSteps(driver, [...provision, ...rollout]);
     print('');
     if (workspace) print(style.dim(`  the workspace would be uploaded to ${workspace}`));
-    print(style.dim('  --dry-run: nothing was run, and no credential was read or written.'));
+    // Not "nothing was run": planning the list above reads the IAM policies this
+    // deploy would change, because what it supersedes is a fact about what is
+    // there. Reads only, and no credential among them.
+    print(style.dim('  --dry-run: nothing was changed, and no credential was read or written.'));
     return;
   }
 
@@ -261,6 +265,7 @@ export async function deploy(flags: DeployFlags): Promise<void> {
   // uploaded is a profile that gets served, and repairing a narrower set than
   // the upload sends would leave a served profile without the surface — this
   // bug again, one profile over.
+  let recorded: DeploymentRecord | null = null;
   if (workspace) {
     // The pre-flight that used to sit here is gone with contract 1. It refused
     // a deploy carrying a profile that did not declare the target, because the
@@ -296,40 +301,26 @@ export async function deploy(flags: DeployFlags): Promise<void> {
     // listing and no writes.
     await migrateWorkspace(workspace, { apply: true });
 
-    // **The target hands itself over to the workspace it now lives in.**
-    //
-    // Two writes, and the order matters. The declaration goes into the bucket's
-    // own `lanes-link.yaml` first, because that is the file the revision coming
-    // up will read to learn where its credentials and bytes are — and a
-    // revision that boots before it lands has nothing to open.
-    //
-    // The local entry then becomes a *pointer*. That is the whole of ADR-052 in
-    // two lines: after this, exactly one file declares this target, and this
-    // machine holds a reference to it rather than a copy. ADR-044's index
-    // existed because the profile's own block was the only record and could be
-    // lost in one edit; there is no second copy left to lose.
-    const stamped = new Date().toISOString();
-
-    await recordTarget(workspace, target, {
-      ...declared,
-      primary: resolution.profile,
-      last_deploy: stamped,
-    });
-
-    // **This machine's registry, not the target's.** `resolution.workspaceRoot`
-    // is the workspace the profile was *found* in, which for a deployed target is
-    // the bucket — so writing the pointer there pointed the bucket at itself, and
-    // the revision that came up refused to open its own target.
-    await recordTarget(resolveWorkspaceRoot(), target, {
+    // Where this deployment lives, in both registries — see `record.ts`. The
+    // declaration has to land before the revision boots, so it goes here rather
+    // than after the rollout; what rolled it is written once it has.
+    recorded = {
       workspace,
+      target,
+      declared,
       primary: resolution.profile,
-      last_deploy: stamped,
-    });
+      at: new Date().toISOString(),
+    };
+    await recordDeployment(recorded);
   }
 
   heading('Rolling out');
   await runSteps(driver, rollout);
 
+  // The release that rolled it, now that it has. `version()` is read from the
+  // installed package, which is the same tree the image was built from.
+  if (recorded) await recordDeployment({ ...recorded, version: version() });
+
   const url = await driver.url(deployConfig);
   if (!url) {
     print(

package/src/deployments/driver.ts

@@ -33,6 +33,17 @@ export interface DeployStep {
   readonly argv: readonly string[];
   /** A step whose failure is expected when the thing already exists. */
   readonly tolerateFailure?: boolean;
+  /**
+   * A step that takes something away rather than creating it.
+   *
+   * Its "already done" is the opposite message: a create that finds the thing
+   * present and a removal that finds it absent are both the expected case on
+   * every deploy after the one that did the work. Told apart explicitly rather
+   * than guessed from the argv, because reading `NOT_FOUND` as success on a step
+   * that was *adding* something would hide the exact failure this repository has
+   * already shipped twice.
+   */
+  readonly removes?: boolean;
 }
 
 export interface PlanInput {

package/src/deployments/gcp/bucket.ts

@@ -0,0 +1,157 @@
+import { layout } from '#profile';
+import type { DeployStep } from '../driver.ts';
+import {
+  removalStep,
+  supersededBindings,
+  type ConditionedGrant,
+  type PolicyReader,
+} from './iam.ts';
+
+/**
+ * The bucket a deployed target keeps everything in, and who may touch what in it.
+ *
+ * Split out of `provision.ts` because it is a different subject from the rest of
+ * that file. Everything else there is "create the thing this deploy needs";
+ * this is one resource's access policy, and it is the only place in the
+ * repository where ADR-007 is enforced by something other than the code being
+ * unable to write.
+ *
+ * Two conditioned bindings rather than one blanket `objectAdmin`, because the
+ * bucket now holds the config as well as the data. ADR-007 says a deployed
+ * instance never mutates its own configuration. That used to be enforced by the
+ * image being read-only, which stopped being true when the workspace moved into
+ * the bucket (ADR-023). This is where the guarantee went: the revision may write
+ * what it owns and may only read what declares what it is.
+ */
+
+/**
+ * The two grants, as data, so the same list drives what is added and what is
+ * recognised as an earlier version of itself.
+ *
+ * A provider manifest is configuration that happens to live inside the profile's
+ * directory (ADR-030), so `data/` alone no longer separates what the revision
+ * owns from what declares what it is.
+ *
+ * **One `startsWith` per profile, because Cloud Storage IAM conditions cannot
+ * express anything else.** Their CEL is a restricted subset — `resource.type`,
+ * `resource.name` with `startsWith`/`endsWith`/`==`, and the date functions —
+ * and it has no `matches`. This was a regex, and it was refused twice over:
+ * first because it spelled the dot `\.`, which is not a CEL escape, so the
+ * string literal would not parse; then, with that fixed, because `matches` is
+ * `undeclared` in this dialect.
+ *
+ * Enumerating the served profiles is expressible in the subset that does exist,
+ * and it makes `grants.test.ts` honest as a side effect: that file evaluates
+ * these as JavaScript, where `startsWith` means what it means here and `matches`
+ * quietly did not.
+ */
+export function bucketGrants(bucket: string, profiles: readonly string[]): ConditionedGrant[] {
+  const objectsUnder = (path: string): string =>
+    `resource.name.startsWith("projects/_/buckets/${bucket}/objects/${path}")`;
+  const objectIs = (path: string): string =>
+    `resource.name == "projects/_/buckets/${bucket}/objects/${path}"`;
+
+  const manifestPrefixes = profiles.map((profile) =>
+    objectsUnder(`${layout.providers(profile)}/`),
+  );
+  // No profiles leaves the carve-out off rather than guessing at one: the
+  // revision keeps write on its own data, as it did before this existed.
+  const manifests = manifestPrefixes.length > 0 ? `(${manifestPrefixes.join(' || ')})` : null;
+
+  return [
+    {
+      // objectAdmin, not objectViewer: state, the log, attachments, memory and
+      // skills are all written by the running endpoint.
+      role: 'roles/storage.objectAdmin',
+      title: 'owns-its-data',
+      expression: `${objectsUnder('data/')}${manifests ? ` && !${manifests}` : ''}`,
+    },
+    {
+      // `expression=true` was here, which is every object in the bucket — the
+      // step title and ADR-023 both claim a narrowing this did not do. The
+      // config the revision reads is the workspace file, the profiles beside it,
+      // and each profile's own manifests, so name exactly those.
+      role: 'roles/storage.objectViewer',
+      title: 'reads-its-config',
+      expression: `${objectsUnder('profiles/')} || ${objectIs('lanes-link.yaml')}${manifests ? ` || ${manifests}` : ''}`,
+    },
+  ];
+}
+
+const TITLES: Record<string, string> = {
+  'owns-its-data': 'let the revision write its own data, but not the manifests in it',
+  'reads-its-config': 'let the revision read its config, and only read it',
+};
+
+/** Everything a deploy does to the bucket: create it, grant, and un-grant. */
+export async function bucketSteps(input: {
+  readonly bucket: string;
+  readonly project: string;
+  readonly region: string;
+  readonly serviceAccount: string | undefined;
+  readonly profiles: readonly string[];
+  readonly policy?: PolicyReader | undefined;
+}): Promise<DeployStep[]> {
+  const steps: DeployStep[] = [
+    {
+      title: `create the bucket gs://${input.bucket}`,
+      argv: [
+        'storage',
+        'buckets',
+        'create',
+        `gs://${input.bucket}`,
+        '--project',
+        input.project,
+        '--location',
+        input.region,
+        // Blobs here are read and written by one instance at a time and never
+        // served publicly; uniform access removes per-object ACLs as a way to
+        // get that wrong.
+        '--uniform-bucket-level-access',
+      ],
+      tolerateFailure: true,
+    },
+  ];
+
+  if (!input.serviceAccount) return steps;
+
+  const member = `serviceAccount:${input.serviceAccount}`;
+  const grants = bucketGrants(input.bucket, input.profiles);
+
+  for (const grant of grants) {
+    steps.push({
+      title: TITLES[grant.title] ?? `bind ${grant.role}`,
+      argv: [
+        'storage',
+        'buckets',
+        'add-iam-policy-binding',
+        `gs://${input.bucket}`,
+        '--member',
+        member,
+        '--role',
+        grant.role,
+        '--condition',
+        `title=${grant.title},expression=${grant.expression}`,
+      ],
+      tolerateFailure: true,
+    });
+  }
+
+  // After the additions above, and only ever after them — see `removalStep`.
+  const current = (await input.policy?.bucket(input.bucket)) ?? null;
+  if (current === null) return steps;
+
+  for (const binding of supersededBindings({ current, member, desired: grants })) {
+    const step = removalStep({
+      resource: ['storage', 'buckets', 'remove-iam-policy-binding', `gs://${input.bucket}`],
+      member,
+      binding,
+      title: binding.condition
+        ? `drop the superseded "${binding.condition.title}" binding an earlier deploy left`
+        : `drop the unconditioned ${binding.role} an earlier deploy left`,
+    });
+    if (step) steps.push(step);
+  }
+
+  return steps;
+}

package/src/deployments/gcp/driver.ts

@@ -13,6 +13,7 @@ import { encodeRef } from '../adapters/gcp-secret-manager.ts';
 import {
   captureGcloud,
   gcloudPath,
+  gcloudPolicy,
   requireProject,
   runGcloud,
   serviceUrl,
@@ -176,7 +177,11 @@ export const cloudRunDriver: DeployDriver = {
   },
 
   provision(input: ProvisionInput): Promise<DeployStep[]> {
-    return provisionSteps(input);
+    // The policy reader is what lets a deploy take away the bindings it
+    // supersedes rather than only add the ones it means. It reads; it changes
+    // nothing, and a `--dry-run` that skipped it would print a plan missing
+    // exactly the steps this deploy exists to make visible.
+    return provisionSteps(input, gcloudPolicy);
   },
 
   plan: deployPlan,

package/src/deployments/gcp/gcloud.ts

@@ -1,5 +1,6 @@
 import { ConfigError, type DeployConfig } from '#profile';
 import type { CommandResult } from '../driver.ts';
+import type { PolicyBinding, PolicyReader } from './iam.ts';
 
 /**
  * Shelling out to `gcloud`.
@@ -176,3 +177,36 @@ export async function openBillingAccounts(): Promise<{ id: string; name: string
     })
     .filter((account) => account.id.length > 0);
 }
+
+/**
+ * The IAM policies a deploy is about to edit, read before it edits them.
+ *
+ * Read rather than remembered. `add-iam-policy-binding` adds a binding beside an
+ * existing one whenever the condition differs, so a deploy that changes a
+ * condition leaves the old one granting whatever it granted — and nothing in
+ * this repository knows what the last deploy wrote (`docs/detailed/init.md`
+ * rules out the state file that would). IAM is what actually decides, so IAM is
+ * what gets asked.
+ *
+ * Every failure answers `null`, which plans no removals at all: a missing
+ * `gcloud`, a bucket that does not exist yet on a first deploy, and a policy
+ * this login may not read are all "could not look", and none of them is a reason
+ * to guess at what to take away.
+ */
+async function readPolicy(argv: readonly string[]): Promise<PolicyBinding[] | null> {
+  const result = await captureGcloud(argv);
+  if (!result.ok) return null;
+
+  try {
+    return (JSON.parse(result.stdout) as { bindings?: PolicyBinding[] }).bindings ?? [];
+  } catch {
+    return null;
+  }
+}
+
+export const gcloudPolicy: PolicyReader = {
+  bucket: (bucket) =>
+    readPolicy(['storage', 'buckets', 'get-iam-policy', `gs://${bucket}`, '--format', 'json']),
+  project: (project) =>
+    readPolicy(['projects', 'get-iam-policy', project, '--format', 'json']),
+};

package/src/deployments/gcp/iam.ts

@@ -0,0 +1,179 @@
+import type { DeployStep } from '../driver.ts';
+
+/**
+ * Bindings a deploy did not write, and what to do about the ones it replaced.
+ *
+ * **`add-iam-policy-binding` adds.** It is keyed on the whole binding —
+ * role, member *and* condition — so changing a condition's expression does not
+ * edit the binding, it writes a second one beside the first. IAM then evaluates
+ * the set as a permissive union: whichever expression is widest wins, and the
+ * narrowing the new one describes never happens.
+ *
+ * That is not hypothetical. Every step in `provision.ts` tolerates failure, so
+ * two rejected attempts at a condition left `reads-its-config` sitting at
+ * `expression=true` — `objectViewer` on every object in the bucket, under a
+ * title claiming the opposite, and the exact state ADR-007 exists to prevent.
+ * Three deploys since have each added a correct binding beside it and changed
+ * nothing about what the revision could read.
+ *
+ * So a deploy has to *remove* what it supersedes, and the removal has to name
+ * the old binding exactly. Nothing here keeps a record of what the last deploy
+ * wrote — `docs/detailed/init.md` rules out state files, leases and drift
+ * reconciliation, and a record would only ever agree with itself anyway. The
+ * policy is read instead: IAM is the thing that actually decides, so IAM is what
+ * gets asked, the same argument `unboundRotatableRefs` makes for `doctor`.
+ */
+
+/** One binding, as `get-iam-policy --format=json` returns it. */
+export interface PolicyBinding {
+  readonly role?: string | undefined;
+  readonly members?: readonly string[] | undefined;
+  readonly condition?:
+    | {
+        readonly title?: string | undefined;
+        readonly expression?: string | undefined;
+        readonly description?: string | undefined;
+      }
+    | undefined;
+}
+
+/** A binding this deploy writes: a role, and the condition that scopes it. */
+export interface ConditionedGrant {
+  readonly role: string;
+  readonly title: string;
+  readonly expression: string;
+}
+
+/**
+ * Reading a policy this deploy is about to change.
+ *
+ * An interface rather than a direct call so `provisionSteps` stays what it is —
+ * a pure function from a target to a list of commands — and so every test of it
+ * runs with no cloud project near it. Absent means "nothing was asked", which
+ * plans no removals at all: a deploy that cannot see the current policy must not
+ * guess at what to take away.
+ */
+export interface PolicyReader {
+  /** The bucket's own policy, or null when it could not be read. */
+  bucket(bucket: string): Promise<readonly PolicyBinding[] | null>;
+  /** The project's policy, on the same contract. */
+  project(project: string): Promise<readonly PolicyBinding[] | null>;
+}
+
+/** Whether an existing binding is exactly one of the grants being applied. */
+function isDesired(binding: PolicyBinding, desired: readonly ConditionedGrant[]): boolean {
+  return desired.some(
+    (grant) =>
+      grant.role === binding.role &&
+      grant.title === binding.condition?.title &&
+      grant.expression === binding.condition?.expression,
+  );
+}
+
+/**
+ * The bindings on this resource that an earlier version of this deploy wrote and
+ * this one no longer means.
+ *
+ * Two shapes qualify, and both are things only a deploy puts there:
+ *
+ *   - **A condition with one of our titles and a different expression.** The
+ *     `owns-its-data` binding that still names `skills/`, the `reads-its-config`
+ *     one still saying `true`. Matched on the title rather than on the role, so
+ *     that changing which role carries a title cleans the old one up too.
+ *   - **An unconditioned binding on a role we only ever grant conditionally.**
+ *     A grant with no condition is the whole bucket, which is the thing the
+ *     condition exists to prevent; there is no version of this deploy for which
+ *     it is the right answer.
+ *
+ * Anything else on the policy is left alone — other members, other roles, and
+ * every binding a human added deliberately.
+ */
+export function supersededBindings(input: {
+  readonly current: readonly PolicyBinding[];
+  readonly member: string;
+  readonly desired: readonly ConditionedGrant[];
+}): PolicyBinding[] {
+  const titles = new Set(input.desired.map((grant) => grant.title));
+  const roles = new Set(input.desired.map((grant) => grant.role));
+
+  return input.current.filter((binding) => {
+    if (!(binding.members ?? []).includes(input.member)) return false;
+    if (isDesired(binding, input.desired)) return false;
+
+    const title = binding.condition?.title;
+    if (title !== undefined) return titles.has(title);
+    return binding.role !== undefined && roles.has(binding.role);
+  });
+}
+
+/**
+ * A condition as `--condition` wants it, delimiter and all.
+ *
+ * gcloud parses this value as comma-separated `key=value` pairs, so an
+ * expression containing a comma silently becomes two keys — and the removal has
+ * to match the stored condition *exactly*, including its description, or it
+ * removes nothing and reports that it removed nothing. The `^X^` prefix picks a
+ * different delimiter, which is gcloud's own escape for this (`gcloud topic
+ * escaping`).
+ *
+ * None of the expressions this repository writes contains a comma. The one being
+ * removed came off the policy, though, and so was written by some other version
+ * of this file.
+ */
+export function conditionFlag(condition: NonNullable<PolicyBinding['condition']>): string {
+  const parts: [string, string][] = [
+    ['title', condition.title ?? ''],
+    ['expression', condition.expression ?? ''],
+    ...(condition.description ? ([['description', condition.description]] as [string, string][]) : []),
+  ];
+
+  const text = parts.map(([key, value]) => `${key}=${value}`).join('');
+  const delimiter = [',', ';', ':', '#', '~', '%'].find((candidate) => !text.includes(candidate));
+  if (delimiter === undefined) {
+    // Six delimiters and every one of them is in the expression. Nothing this
+    // repository writes gets here; a binding that does is left in place rather
+    // than removed by an argv that would mean something else.
+    return '';
+  }
+
+  const joined = parts.map(([key, value]) => `${key}=${value}`).join(delimiter);
+  return delimiter === ',' ? joined : `^${delimiter}^${joined}`;
+}
+
+/**
+ * The command that takes one superseded binding away.
+ *
+ * Always after the step that adds its replacement, never before. The two are one
+ * edit to a live policy, and doing them the other way round opens a window —
+ * seconds by the clock, longer once propagation is counted — in which the
+ * revision that is currently serving holds no grant at all.
+ *
+ * `null` for a binding whose condition cannot be spelled as an argument, which
+ * leaves it in place: an approximate `--condition` matches nothing, or worse,
+ * matches something else.
+ */
+export function removalStep(input: {
+  readonly resource: readonly string[];
+  readonly member: string;
+  readonly binding: PolicyBinding;
+  readonly title: string;
+}): DeployStep | null {
+  const condition = input.binding.condition;
+  const flag = condition ? conditionFlag(condition) : 'None';
+  if (flag === '') return null;
+
+  return {
+    title: input.title,
+    argv: [
+      ...input.resource,
+      '--member',
+      input.member,
+      '--role',
+      input.binding.role ?? '',
+      '--condition',
+      flag,
+    ],
+    tolerateFailure: true,
+    removes: true,
+  };
+}

package/src/deployments/gcp/provision.ts

@@ -1,8 +1,9 @@
 import { VAULT_DOCUMENT_REF, type SecretRef } from '#secrets';
 import type { DeployStep, ProvisionInput } from '../driver.ts';
 import { encodeRef } from '../adapters/gcp-secret-manager.ts';
-import { layout } from '#profile';
+import { bucketSteps } from './bucket.ts';
 import { requireProject } from './gcloud.ts';
+import type { PolicyReader } from './iam.ts';
 
 /**
  * The project-level things a Cloud Run deploy needs to already exist.
@@ -56,6 +57,44 @@ export interface SecretGrant {
   readonly refs: readonly SecretRef[];
 }
 
+/**
+ * Bring each secret into existence, so the bindings below have something to
+ * attach to and the revision never needs `secrets.create` itself.
+ *
+ * That second half is the reason this is a step rather than left to whoever
+ * writes the value: `secretmanager.secrets.create` is a project-level
+ * permission, and a revision holding it could mint credential references of its
+ * own. So the container is created here and the revision only ever adds a
+ * version.
+ *
+ * The first half is why *read* grants need it too, which they did not have. A
+ * binding cannot attach to a secret that does not exist — `gcloud` answers
+ * `NOT_FOUND`, every step here tolerates failure, and the deploy carries on. On
+ * a first deploy that is exactly what happened to the endpoint's own bearer
+ * token: `prepareSecrets` mints it *after* provisioning, so the secret appeared
+ * a step too late to be bound and the revision could not read the one value it
+ * refuses to start without. A second deploy fixed it, which is why this survived
+ * — the failure only ever showed up once per project.
+ */
+export function createSteps(input: {
+  readonly project: string;
+  readonly refs: readonly SecretRef[];
+}): DeployStep[] {
+  return input.refs.map((ref) => ({
+    title: `create the secret ${encodeRef(ref)}, so the revision never needs secrets.create`,
+    argv: [
+      'secrets',
+      'create',
+      encodeRef(ref),
+      '--project',
+      input.project,
+      '--replication-policy',
+      'automatic',
+    ],
+    tolerateFailure: true,
+  }));
+}
+
 /** Read, named one secret at a time, so the grant needs no condition to be scoped. */
 export function readSteps({ project, serviceAccount, refs }: SecretGrant): DeployStep[] {
   return refs.map((ref) => ({
@@ -80,39 +119,32 @@ export function readSteps({ project, serviceAccount, refs }: SecretGrant): Deplo
 }
 
 /**
- * Write, two steps each, and the first is what keeps the second narrow: the
- * secret is created here so the revision only ever needs to *add a version*,
- * never `secrets.create`, which is a project-level permission that would let it
- * mint credential references of its own.
+ * Write, named one secret at a time, and never `secrets.create` — the container
+ * is made by `createSteps` so this grant can stay at "add a version".
  */
 export function rotateSteps({ project, serviceAccount, refs }: SecretGrant): DeployStep[] {
-  return refs.flatMap((ref) => {
-    const id = encodeRef(ref);
-    return [
-      {
-        title: `create the secret ${id}, so the revision never needs secrets.create`,
-        argv: ['secrets', 'create', id, '--project', project, '--replication-policy', 'automatic'],
-        tolerateFailure: true,
-      },
-      {
-        title: `let the revision rewrite ${ref}, and nothing else in the store`,
-        argv: [
-          'secrets',
-          'add-iam-policy-binding',
-          id,
-          '--project',
-          project,
-          '--member',
-          `serviceAccount:${serviceAccount}`,
-          '--role',
-          'roles/secretmanager.secretVersionAdder',
-          '--condition',
-          'None',
-        ],
-        tolerateFailure: true,
-      },
-    ];
-  });
+  return refs.map((ref) => ({
+    title: `let the revision rewrite ${ref}, and nothing else in the store`,
+    argv: [
+      'secrets',
+      'add-iam-policy-binding',
+      encodeRef(ref),
+      '--project',
+      project,
+      '--member',
+      `serviceAccount:${serviceAccount}`,
+      '--role',
+      'roles/secretmanager.secretVersionAdder',
+      '--condition',
+      'None',
+    ],
+    tolerateFailure: true,
+  }));
+}
+
+/** The union of two ref lists, deduplicated and ordered, so nothing is created twice. */
+function union(...lists: readonly (readonly SecretRef[])[]): SecretRef[] {
+  return [...new Set(lists.flat())].sort();
 }
 
 /**
@@ -142,12 +174,74 @@ export function secretGrantSteps(
 ): DeployStep[] {
   const { project, serviceAccount } = grant;
   return [
+    ...createSteps({ project, refs: union(grant.readable, grant.rotatable) }),
     ...readSteps({ project, serviceAccount, refs: grant.readable }),
     ...rotateSteps({ project, serviceAccount, refs: grant.rotatable }),
   ];
 }
 
-export function provisionSteps(input: ProvisionInput): Promise<DeployStep[]> {
+/**
+ * The project-wide secret read that per-secret bindings replaced.
+ *
+ * `roles/secretmanager.secretAccessor` on the whole project is what this deploy
+ * used to grant, and removing it from the code did not remove it from anybody's
+ * project: `add-iam-policy-binding` never took it away, and IAM unions what is
+ * there. It kept working, which is the problem — a connection made after a
+ * deploy could still be *read* by the revision through this binding while its
+ * per-secret grant was missing, so the connection authorised, answered, and
+ * reported `active` until the first token refresh needed a write. An hour of
+ * looking healthy, and then a 403 nowhere near its cause.
+ *
+ * Only ever removed when this run granted read per secret. With no `readable`
+ * set there is nothing to fall back to, and taking away the only grant the
+ * revision has would be an outage caused by tidying.
+ */
+async function projectReadRemoval(input: {
+  readonly project: string;
+  readonly member: string;
+  readonly readable: readonly SecretRef[];
+  readonly policy: PolicyReader | undefined;
+}): Promise<DeployStep[]> {
+  if (input.readable.length === 0 || !input.policy) return [];
+
+  const current = await input.policy.project(input.project);
+  const present = (current ?? []).some(
+    (binding) =>
+      binding.role === 'roles/secretmanager.secretAccessor' &&
+      (binding.members ?? []).includes(input.member),
+  );
+  if (!present) return [];
+
+  return [
+    {
+      title: 'drop the project-wide secret read the per-secret grants replaced',
+      argv: [
+        'projects',
+        'remove-iam-policy-binding',
+        input.project,
+        '--member',
+        input.member,
+        '--role',
+        'roles/secretmanager.secretAccessor',
+        // Irrespective of any condition: every shape of this binding is one an
+        // earlier version of this file wrote, and all of them are superseded.
+        '--all',
+      ],
+      tolerateFailure: true,
+      removes: true,
+    },
+  ];
+}
+
+export async function provisionSteps(
+  input: ProvisionInput,
+  /**
+   * How to read the policies this deploy is about to change, so it can take away
+   * what it supersedes as well as add what it means. Absent plans no removals —
+   * see `PolicyReader`.
+   */
+  policy?: PolicyReader,
+): Promise<DeployStep[]> {
   const cloudrun = requireProject(input.deploy, input.target);
   const { project, region, service_account: serviceAccount } = cloudrun;
   const steps: DeployStep[] = [];
@@ -206,6 +300,25 @@ export function provisionSteps(input: ProvisionInput): Promise<DeployStep[]> {
       tolerateFailure: true,
     });
 
+    // What a revision rewrites in its own credential store, named one secret at
+    // a time. Two kinds, and they arrive from different places:
+    //
+    //   - the vault document, because `vault.put` is a capability an agent may
+    //     hold under policy (ADR-022);
+    //   - each connection's OAuth token, because a refresh persists and serving
+    //     a request is what triggers it (ADR-026).
+    //
+    // The second was missing, and the shape of the miss is worth keeping in
+    // mind: nothing here was wrong, it was incomplete, and being incomplete
+    // looked exactly like being finished. Reading mail 403'd an hour after every
+    // deploy.
+    const rotatable = [
+      ...(input.declared.vault?.adapter === 'secret'
+        ? [input.declared.vault.ref ?? VAULT_DOCUMENT_REF]
+        : []),
+      ...(input.rotatable ?? []),
+    ];
+
     // Read, named one secret at a time, for the same reason the write side is:
     // a resource-level grant needs no condition to be scoped.
     //
@@ -220,37 +333,19 @@ export function provisionSteps(input: ProvisionInput): Promise<DeployStep[]> {
     // Affordable because the serving path reads by explicit ref: `list()` is a
     // CLI call, and `secretAccessor` never carried `secrets.list` anyway.
     // `readableRefs` derives the set from config and manifests at deploy time.
-    steps.push(...readSteps({ project, serviceAccount, refs: input.readable ?? [] }));
-  }
+    const readable = input.readable ?? [];
 
-  // What a revision rewrites in its own credential store, named one secret at a
-  // time. Two kinds, and they arrive from different places:
-  //
-  //   - the vault document, because `vault.put` is a capability an agent may
-  //     hold under policy (ADR-022);
-  //   - each connection's OAuth token, because a refresh persists and serving a
-  //     request is what triggers it (ADR-026).
-  //
-  // The second was missing, and the shape of the miss is worth keeping in mind:
-  // nothing here was wrong, it was incomplete, and being incomplete looked
-  // exactly like being finished. Reading mail 403'd an hour after every deploy.
-  //
-  // Two steps each, and the first is what keeps the second narrow: the secret is
-  // created here so the revision only ever needs to *add a version*, never
-  // `secrets.create`, which is a project-level permission that would let it mint
-  // credential refs of its own. The binding is on the one secret, so it needs no
-  // condition to be scoped — a resource-level grant already is.
-  const writable = serviceAccount
-    ? [
-        ...(input.declared.vault?.adapter === 'secret'
-          ? [input.declared.vault.ref ?? VAULT_DOCUMENT_REF]
-          : []),
-        ...(input.rotatable ?? []),
-      ]
-    : [];
-
-  if (serviceAccount) {
-    steps.push(...rotateSteps({ project, serviceAccount, refs: writable }));
+    steps.push(...createSteps({ project, refs: union(readable, rotatable) }));
+    steps.push(...readSteps({ project, serviceAccount, refs: readable }));
+    steps.push(...rotateSteps({ project, serviceAccount, refs: rotatable }));
+    steps.push(
+      ...(await projectReadRemoval({
+        project,
+        member: `serviceAccount:${serviceAccount}`,
+        readable,
+        policy,
+      })),
+    );
   }
 
   // Any target that addresses a bucket, which deployed means all of them:
@@ -263,110 +358,17 @@ export function provisionSteps(input: ProvisionInput): Promise<DeployStep[]> {
     input.declared.storage.adapter === 'gcs' || input.declared.storage.adapter === 's3';
   const bucket = usesBucket ? input.declared.storage.bucket : undefined;
   if (bucket) {
-    steps.push({
-      title: `create the bucket gs://${bucket}`,
-      argv: [
-        'storage',
-        'buckets',
-        'create',
-        `gs://${bucket}`,
-        '--project',
+    steps.push(
+      ...(await bucketSteps({
+        bucket,
         project,
-        '--location',
         region,
-        // Blobs here are read and written by one instance at a time and never
-        // served publicly; uniform access removes per-object ACLs as a way to
-        // get that wrong.
-        '--uniform-bucket-level-access',
-      ],
-      tolerateFailure: true,
-    });
-
-    if (serviceAccount) {
-      // Two conditioned bindings rather than one blanket objectAdmin, because
-      // the bucket now holds the config as well as the data.
-      //
-      // ADR-007 says a deployed instance never mutates its own configuration.
-      // That used to be enforced by the image being read-only, which stopped
-      // being true when the workspace moved into the bucket (ADR-023). This is
-      // where the guarantee went: the revision may write what it owns and may
-      // only read what declares what it is.
-      const objectsUnder = (path: string): string =>
-        `resource.name.startsWith("projects/_/buckets/${bucket}/objects/${path}")`;
-      const objectIs = (path: string): string =>
-        `resource.name == "projects/_/buckets/${bucket}/objects/${path}"`;
-
-      // A provider manifest is configuration that happens to live inside the
-      // profile's directory (ADR-030), so `data/` alone no longer separates what
-      // the revision owns from what declares what it is.
-      //
-      // **One `startsWith` per profile, because Cloud Storage IAM conditions
-      // cannot express anything else.** Their CEL is a restricted subset —
-      // `resource.type`, `resource.name` with `startsWith`/`endsWith`/`==`, and
-      // the date functions — and it has no `matches`. This was a regex, and it
-      // was refused twice over: first because it spelled the dot `\.`, which is
-      // not a CEL escape, so the string literal would not parse; then, with that
-      // fixed, because `matches` is `undeclared` in this dialect.
-      //
-      // Both bindings carry `tolerateFailure`, so each attempt printed a warning
-      // and left whatever conditions the bucket already had. On a real
-      // deployment that was `expression=true` on the read binding — every object
-      // in the bucket, the exact opposite of the narrowing the step title claims,
-      // and the state ADR-007 says must not exist.
-      //
-      // Enumerating the served profiles is expressible in the subset that does
-      // exist, and it makes `grants.test.ts` honest as a side effect: that file
-      // evaluates these as JavaScript, where `startsWith` means what it means
-      // here and `matches` quietly did not.
-      const manifestPrefixes = (input.profiles ?? []).map((profile) =>
-        objectsUnder(`${layout.providers(profile)}/`),
-      );
-      // No profiles leaves the carve-out off rather than guessing at one: the
-      // revision keeps write on its own data, as it did before this existed.
-      const providerManifests =
-        manifestPrefixes.length > 0 ? `(${manifestPrefixes.join(' || ')})` : null;
-
-      steps.push({
-        title: 'let the revision write its own data, but not the manifests in it',
-        argv: [
-          'storage',
-          'buckets',
-          'add-iam-policy-binding',
-          `gs://${bucket}`,
-          '--member',
-          `serviceAccount:${serviceAccount}`,
-          // objectAdmin, not objectViewer: state, the log, attachments, memory
-          // and skills are all written by the running endpoint.
-          '--role',
-          'roles/storage.objectAdmin',
-          '--condition',
-          `title=owns-its-data,expression=${objectsUnder('data/')}${providerManifests ? ` && !${providerManifests}` : ''}`,
-        ],
-        tolerateFailure: true,
-      });
-
-      steps.push({
-        title: 'let the revision read its config, and only read it',
-        argv: [
-          'storage',
-          'buckets',
-          'add-iam-policy-binding',
-          `gs://${bucket}`,
-          '--member',
-          `serviceAccount:${serviceAccount}`,
-          '--role',
-          'roles/storage.objectViewer',
-          // `expression=true` was here, which is every object in the bucket —
-          // the step title and ADR-023 both claim a narrowing this did not do.
-          // The config the revision reads is the workspace file, the profiles
-          // beside it, and each profile's own manifests, so name exactly those.
-          '--condition',
-          `title=reads-its-config,expression=${objectsUnder('profiles/')} || ${objectIs('lanes-link.yaml')}${providerManifests ? ` || ${providerManifests}` : ''}`,
-        ],
-        tolerateFailure: true,
-      });
-    }
+        serviceAccount,
+        profiles: input.profiles ?? [],
+        policy,
+      })),
+    );
   }
 
-  return Promise.resolve(steps);
+  return steps;
 }

package/src/deployments/record.ts

@@ -0,0 +1,62 @@
+import { recordTarget, resolveWorkspaceRoot, type TargetConfig } from '#profile';
+
+/**
+ * Writing down where a deployment lives, and what rolled it.
+ *
+ * **The target hands itself over to the workspace it now lives in.** Two writes,
+ * and the order matters. The declaration goes into the bucket's own
+ * `lanes-link.yaml` first, because that is the file the revision coming up will
+ * read to learn where its credentials and bytes are — and a revision that boots
+ * before it lands has nothing to open.
+ *
+ * The local entry then becomes a *pointer*. That is the whole of ADR-052 in two
+ * lines: after this, exactly one file declares this target, and this machine
+ * holds a reference to it rather than a copy. ADR-044's index existed because
+ * the profile's own block was the only record and could be lost in one edit;
+ * there is no second copy left to lose.
+ */
+
+export interface DeploymentRecord {
+  /** Where the target's own workspace lives — the bucket, for a deployment. */
+  readonly workspace: string;
+  readonly target: string;
+  readonly declared: TargetConfig;
+  /** Whose bearer token opens the endpoint (ADR-009). */
+  readonly primary: string;
+  /** When this deploy ran, as an ISO instant. */
+  readonly at: string;
+  /**
+   * The CLI release that rolled the revision, written only once it has rolled.
+   *
+   * The image is built from the installed package, so the version planning the
+   * deploy *is* the version serving it — which makes this the one place either
+   * end can be asked "what is up there" without a running endpoint to ask. The
+   * bucket carries it as well as the laptop, so a second machine reading the
+   * registry learns it too.
+   *
+   * Absent on the write that happens before the rollout, and that asymmetry is
+   * the point: a build that fails must not leave a version recorded that never
+   * served a request. The declaration has to land first (a revision that boots
+   * without it has nothing to open); the version can only be true afterwards.
+   */
+  readonly version?: string | undefined;
+}
+
+export async function recordDeployment(record: DeploymentRecord): Promise<void> {
+  const stamp = {
+    primary: record.primary,
+    last_deploy: record.at,
+    ...(record.version ? { last_deploy_version: record.version } : {}),
+  };
+
+  await recordTarget(record.workspace, record.target, { ...record.declared, ...stamp });
+
+  // **This machine's registry, not the target's.** The workspace a profile was
+  // *found* in is the bucket for a deployed target — so writing the pointer
+  // there pointed the bucket at itself, and the revision that came up refused to
+  // open its own target.
+  await recordTarget(resolveWorkspaceRoot(), record.target, {
+    workspace: record.workspace,
+    ...stamp,
+  });
+}

package/src/deployments/steps.ts

@@ -60,6 +60,36 @@ export function isAlreadyThere(stderr: string): boolean {
   return EXISTS.test(stderr);
 }
 
+/**
+ * The same thing, for a step that takes something away.
+ *
+ * A deploy removes the IAM bindings it supersedes, and a binding that is already
+ * gone is that step succeeding: the second deploy after the one that removed it
+ * finds nothing to remove, exactly as the second deploy after a create finds the
+ * thing present. Without this it reads as a warning, and a successful deploy
+ * printing warnings for its expected case teaches an operator to skim past the
+ * output that matters.
+ */
+const GONE = /NOT_FOUND|not found|does not exist|no such|cannot find|HTTPError 404/i;
+
+export function isAlreadyGone(stderr: string): boolean {
+  return GONE.test(stderr);
+}
+
+/**
+ * What a tolerated failure was, when it was this step's expected case.
+ *
+ * Keyed on what the step *does*, not on the message alone. `NOT_FOUND` from a
+ * removal is the work already being done; the same word from a step that binds a
+ * role means the secret it was binding does not exist, which is a deploy rolling
+ * a revision that cannot read its own token — the failure that has to stay
+ * visible.
+ */
+export function expectedOutcome(step: DeployStep, stderr: string): string | null {
+  if (step.removes === true) return isAlreadyGone(stderr) ? 'already gone' : null;
+  return isAlreadyThere(stderr) ? 'already there' : null;
+}
+
 /**
  * Spent across the whole run rather than per step.
  *
@@ -112,11 +142,12 @@ export async function runSteps(
     if (step.tolerateFailure) {
       // The expected case on every deploy after the first, said as such.
       // Anything else it tolerated is still worth seeing, because a tolerated
-      // failure that is not "already there" is how a deploy rolls a revision
-      // with no service account and finds out several minutes later.
+      // failure that is not this step's expected case is how a deploy rolls a
+      // revision with no service account and finds out several minutes later.
+      const expected = expectedOutcome(step, result.stderr);
       print(
-        isAlreadyThere(result.stderr)
-          ? style.dim(`    ${style.green('=')} already there`)
+        expected !== null
+          ? style.dim(`    ${style.green('=')} ${expected}`)
           : warn(`  ${firstLine(result.stderr)}`),
       );
       continue;

package/src/profile/deployments.ts

@@ -63,6 +63,9 @@ function pick(previous: WorkspaceTarget | undefined): Partial<WorkspaceTarget> {
   return {
     ...(previous.primary ? { primary: previous.primary } : {}),
     ...(previous.last_deploy ? { last_deploy: previous.last_deploy } : {}),
+    ...(previous.last_deploy_version
+      ? { last_deploy_version: previous.last_deploy_version }
+      : {}),
   };
 }
 

package/src/profile/registry.ts

@@ -42,7 +42,7 @@ export interface ResolvedTarget {
   readonly workspaceRoot: string;
   /** The adapter set, from whichever workspace declares it. */
   readonly declared: TargetConfig;
-  /** The declaring entry, for `primary` and `last_deploy`. */
+  /** The declaring entry, for `primary` and the deploy record. */
   readonly entry: WorkspaceTarget;
   /** Whether the local workspace reached this through a pointer. */
   readonly remote: boolean;
@@ -107,10 +107,11 @@ export async function openTarget(root: string, target: string): Promise<Resolved
   const declared = declaredTarget(remoteEntry);
   if (!declared) throw incompleteTarget(target, workspaceRoot);
 
-  // The local entry's `primary` and `last_deploy` are what `deploy` wrote on the
-  // machine that ran it; the declaring workspace is authoritative for everything
-  // else. Merged this way round so a redeploy from a second machine does not
-  // silently lose the first one's record of who opens the endpoint.
+  // The local entry's `primary`, `last_deploy` and `last_deploy_version` are what
+  // `deploy` wrote on the machine that ran it; the declaring workspace is
+  // authoritative for everything else. Merged this way round so a redeploy from a
+  // second machine does not silently lose the first one's record of who opens the
+  // endpoint.
   return {
     target,
     workspaceRoot,

package/src/profile/schema.ts

@@ -433,6 +433,20 @@ export const workspaceTargetSchema = z
      */
     primary: identifier.optional(),
     last_deploy: z.string().optional(),
+    /**
+     * The CLI release that rolled the revision serving this target.
+     *
+     * Written by `deploy`, after the rollout rather than before it, so a build
+     * that failed does not leave a version recorded that never served anything.
+     * The image is built from the installed package, so the CLI that ran the
+     * deploy is the code running up there — which makes this the only way to ask
+     * "what version is the endpoint" without an endpoint answering.
+     *
+     * In the target's own workspace as well as on the machine that deployed it:
+     * a second laptop reading the registry learns it too, and `target show`
+     * prints it beside `last_deploy`.
+     */
+    last_deploy_version: z.string().optional(),
   })
   .superRefine((entry, ctx) => {
     const declares = entry.credentials !== undefined || entry.storage !== undefined;