@lanes-sh/link 0.7.2 → 0.9.0

package/src/cli/runtime/open.ts

@@ -1,16 +1,22 @@
 import { BearerAuthenticator, ownerPrincipal } from '#auth';
 import type { SecretStore } from '#secrets';
 import type { AuditReader } from '#audit';
-import type { RuntimeState } from '#stores/state';
+import { DISCOVERY_NAMESPACE, type RuntimeState } from '#stores/state';
 import type { BlobStore } from '#stores/blobs';
 import type { AnyConnector, ProviderManifest } from '#connectivity';
 import { RateLimiter, allowedConnections } from '#policy';
 import {
+  assertGrantsResolve,
   layout,
   listProfiles,
+  readConnections,
+  selectConnections,
+  soleGrantFor,
   workspacePath,
   type Config,
+  type ConnectionConfig,
   type Resolution,
+  type SelectedConnection,
   type TargetConfig,
 } from '#profile';
 import { ProviderRegistry, toPolicyDocument } from '#registry';
@@ -33,6 +39,10 @@ import { resolveProfile, type GlobalFlags } from './select.ts';
 import { buildRegistryWithWorkspace, readSkillsForStart, reloadSkills } from './registry.ts';
 import { discoveryProbe } from './discovery.ts';
 import { openVault } from './vault.ts';
+import { EMPTY_SKILL_STORE, skillStore } from './stores.ts';
+import type { Runtime } from './types.ts';
+
+export type { Runtime } from './types.ts';
 
 /**
  * Assembling a profile's runtime from its declared target.
@@ -43,86 +53,20 @@ import { openVault } from './vault.ts';
  * nothing at the application layer.
  */
 
-export interface Runtime {
-  readonly resolution: Resolution;
-  readonly config: Config;
-  readonly target: string;
-  /**
-   * The target's adapter set, from the workspace that declares it.
-   *
-   * Here because the config no longer carries it. Every caller that used to
-   * reach `config.targets[target]` — for a `deploy` block, a storage adapter, a
-   * knowledge repository — reads this instead, and reads it without following
-   * the pointer a second time (ADR-052).
-   */
-  readonly declared: TargetConfig;
-  readonly state: RuntimeState;
-  /** The durable log, for reading. Copies, if any, are write-only and not here. */
-  readonly audit: AuditReader;
-  readonly credentials: SecretStore;
-  readonly storage: BlobStore;
-  /** Where skills are kept — `data/<profile>/skills.d/` locally. */
-  readonly skills: BlobStore;
-  /**
-   * Present only when this target keeps memory and skills in a repository.
-   *
-   * Nothing on the dispatch path reads it: `storage` and `skills` above are
-   * already pointed at the right bytes, which is the whole design. It is here
-   * so `target show` and `doctor` can say where those bytes are without
-   * re-reading the config, and so the migration can reach the repository it is
-   * committing to.
-   */
-  readonly knowledge?: KnowledgeStores | undefined;
-  /** The vault's own store, so `lanes link vault` reaches the same bytes MCP does. */
-  readonly vault: VaultStore;
-  readonly registry: ProviderRegistry;
-  /**
-   * Re-read the skills into the registry when they have changed on the store.
-   *
-   * Cheap and idempotent — one `list()`, and a rebuild only when the listing
-   * differs from the last one. The caller decides how often to ask.
-   */
-  refreshSkills(): Promise<void>;
-  readonly dispatcher: Dispatcher;
-  readonly authenticator: BearerAuthenticator;
-  /** Same factory the dispatcher uses, exposed for commands that probe upstream. */
-  connectorFor(providerId: string, connectionId: string): AnyConnector | undefined;
-  /**
-   * Same authorizer the dispatcher uses, for the same reason `connectorFor` is here.
-   *
-   * A command that probes upstream needs the credential on the request, and it
-   * must not learn how to put it there — that is one switch on the resolved
-   * shape (`connectivity/auth/authorize.ts`) and a second copy would be a
-   * second answer. `settleIdentity` is the caller: it asks a provider whose
-   * account was just authorised, over whatever method that provider declares.
-   */
-  authorizeRequest(providerId: string, connectionId: string, request: Request): Promise<Request>;
-  /** A provider's manifest, so an omitted `credential_ref` can be derived from it. */
-  manifestFor(providerId: string): ProviderManifest | undefined;
-  close(): Promise<void>;
-}
-
 /**
- * Where this profile's skills live, in either target.
- *
- * Locally `data/<profile>/skills.d/`; deployed, the same key under the bucket
- * prefix. Going through the store rather than a filesystem path is what gives a
- * deployment skills at all — a path is baked into a container image at build
- * time and an object key is not, so before ADR-014 a deployed instance could
- * only ever serve the skills that existed when its image was built.
+ * The accounts a profile reaches, as most callers want them.
  *
- * **Per profile**, which reverses ADR-012 §1. Policy gating `skills.<name>`
- * was the whole isolation story while the bytes were shared, and it is a weak
- * one: it decides who may *run* a procedure, not who may read that it exists or
- * what it says. A skill written for work names work's accounts and work's
- * people. ADR-030.
- *
- * An explicit area, matching `openState` and `openAudit` — a profile that
- * declares its own `storage.path` moves its provider blobs, not the reserved
- * roots beside them.
+ * `runtime.connections` pairs each with the grant governing it, which is what
+ * policy and the setup surface need. Everything else — probing credentials,
+ * listing accounts, reconciling state — wants the rows alone, and unwrapping
+ * them at twenty call sites is twenty chances to reach for
+ * `workspaceConnections` by mistake and answer for accounts this profile was
+ * never granted.
  */
-function skillStore(storage: StorageFactory, profile: string): BlobStore {
-  return storage(layout.skills(profile));
+export function grantedConnections(
+  runtime: Pick<Runtime, 'connections'>,
+): ConnectionConfig[] {
+  return runtime.connections.map(({ connection }) => connection);
 }
 
 /**
@@ -152,6 +96,15 @@ export async function openRuntime(
   const root = resolved.workspaceRoot;
   const adapters: TargetInput = { declared, config, root, target };
 
+  // The workspace's accounts, and the check that this profile's grants name
+  // real ones (ADR-057). Read here rather than inside `resolveProfile` because
+  // it is a property of the workspace rather than of the selection, and because
+  // a command that only wants to know which profiles exist should not have to
+  // parse every connection to find out.
+  const connectionsFile = await readConnections(root);
+  assertGrantsResolve(config, connectionsFile.connections);
+  const selected = selectConnections(config, connectionsFile.connections);
+
   // Credentials first: an S3 key pair is itself a credential reference, so the
   // credential store has to exist before the blob store that names it. State
   // and the log then ride that blob store rather than opening backends of
@@ -187,7 +140,18 @@ export async function openRuntime(
     (message) => logger.warn(message),
   );
 
-  const skills = knowledge?.skills ?? skillStore(storageFor, config.instance.profile);
+  // Rooted at the skills connection this profile grants, not at the profile
+  // (ADR-059). At most one can be granted, which is what makes this a lookup
+  // rather than a choice — `load.ts` refuses a second one, for the reason a
+  // prompt has no argument to route on.
+  //
+  // `EMPTY_SKILLS` when none is granted: a profile that denies `skills.*` has
+  // no store to open, and handing it the workspace root instead would serve
+  // every other profile's procedures.
+  const skillsConnection = soleGrantFor(config, 'lanes_skills');
+  const skills =
+    knowledge?.skills ??
+    (skillsConnection === undefined ? undefined : skillStore(storageFor, config.instance.profile, skillsConnection));
 
   // The vault's own store, beside the credential store and never it: a separate
   // document, a separate key, and a separate environment variable
@@ -208,6 +172,7 @@ export async function openRuntime(
   let registry: ProviderRegistry;
   let fingerprint = '';
   const refreshSkills = async (): Promise<void> => {
+    if (skills === undefined) return;
     fingerprint = await reloadSkills(registry, skills, fingerprint, refreshSkills);
   };
 
@@ -226,23 +191,18 @@ export async function openRuntime(
   // registered into. Per call rather than a snapshot, so a policy the runtime
   // was opened with is re-evaluated rather than remembered.
   const reachable = (): ReadonlyArray<{ key: string; provider: string; account: string }> =>
-    config.connections
-      .filter((connection) =>
+    selected
+      .filter(({ ref, connection }) =>
         registry
           .capabilities()
           .some(
             ({ id }) =>
               id.startsWith(`${connection.provider}.`) &&
-              allowedConnections(
-                id,
-                [`${connection.provider}.${connection.id}`],
-                principal,
-                policy,
-              ).length > 0,
+              allowedConnections(id, [ref], principal, policy).length > 0,
           ),
       )
-      .map((connection) => ({
-        key: `${connection.provider}.${connection.id}`,
+      .map(({ ref, connection }) => ({
+        key: ref,
         provider: connection.provider,
         account: connection.account,
         ...(connection.label ? { label: connection.label } : {}),
@@ -253,14 +213,14 @@ export async function openRuntime(
   // tolerated when the store is a repository: a local directory that will not
   // read is a real fault worth failing on, exactly as it always was.
   const loaded = await readSkillsForStart(
-    skills,
+    skills ?? EMPTY_SKILL_STORE,
     knowledge !== undefined,
     (message) => logger.warn(message),
-    ` --profile ${config.instance.profile} --target ${target}`,
+    ` --profile ${config.instance.profile} --workspace ${target}`,
   );
 
-  registry = await buildRegistryWithWorkspace(root, config.instance.profile, {
-    skillStore: skills,
+  registry = await buildRegistryWithWorkspace(root, {
+    ...(skills ? { skillStore: skills } : {}),
     skills: loaded.skills,
     onSkillsChanged: refreshSkills,
     vault: { store: vaultStore, items: await vaultStore.ids() },
@@ -269,7 +229,7 @@ export async function openRuntime(
       target,
       profiles: await listProfiles(root),
       catalogue: PROVIDER_MANIFESTS,
-      ownClients: Object.keys(config.oauth_apps),
+      ownClients: Object.keys(connectionsFile.oauth_apps),
       reachable,
     },
     // Straight off the config: unlike `reachable`, nothing has to be filtered
@@ -309,7 +269,7 @@ export async function openRuntime(
       }
     }
 
-    const cached = await state.kv.get('discovery', entry.manifest.id);
+    const cached = await state.kv.get(DISCOVERY_NAMESPACE, entry.manifest.id);
     if (cached) {
       try {
         registry.setDiscovered(entry.manifest.id, JSON.parse(cached));
@@ -329,14 +289,16 @@ export async function openRuntime(
     credentials,
     // From the connection row, which is where a per-connection setting has
     // always lived. One lookup behind both, so they cannot disagree.
-    connectionConfig: (provider, id) => row(config, provider, id)?.config,
-    isDeclared: (provider, id) => row(config, provider, id) !== undefined,
+    connectionConfig: (provider, id) => row(connectionsFile.connections, provider, id)?.config,
+    isDeclared: (provider, id) => row(connectionsFile.connections, provider, id) !== undefined,
   });
   const authorizeRequest = requestAuthorizer(registry, credentials);
   let closed = false;
 
   const dispatcher = new Dispatcher({
     config,
+    connections: connectionsFile.connections,
+    oauthApps: Object.keys(connectionsFile.oauth_apps),
     registry,
     connectorFor,
     authorizeRequest,
@@ -354,6 +316,9 @@ export async function openRuntime(
     config,
     target,
     declared,
+    connections: selected,
+    workspaceConnections: connectionsFile.connections,
+    ownClients: Object.keys(connectionsFile.oauth_apps),
     state,
     audit,
     credentials,
@@ -390,5 +355,5 @@ export async function openRuntime(
   };
 }
 
-const row = (config: Config, provider: string, id: string) =>
-  config.connections.find((connection) => connection.provider === provider && connection.id === id);
+const row = (connections: readonly ConnectionConfig[], provider: string, id: string) =>
+  connections.find((connection) => connection.provider === provider && connection.id === id);

package/src/cli/runtime/registry.ts

@@ -3,7 +3,7 @@ import type { ProviderDefinition } from '#connectivity';
 import { ConfigError } from '#profile';
 import { ProviderRegistry } from '#registry';
 import { RESERVED_BY_GRAMMAR } from '../commands/connect/custom/spec.ts';
-import { loadProfileProviders } from '#providers/custom/index.ts';
+import { loadWorkspaceProviders } from '#providers/custom/index.ts';
 import { loadProfileSkills, type LoadedSkill } from '#providers/skills/store.ts';
 import { exampleProvider } from '#providers/example/provider.ts';
 import {
@@ -138,21 +138,20 @@ export function buildRegistry(owner: OwnerLayerOptions = {}): ProviderRegistry {
  * overriding it — an operator shadowing `gmail` by accident would be very hard
  * to diagnose from the outside.
  *
- * The profile is a parameter rather than read from a config here because two of
- * the three callers do not have one: `deploy` walks every profile in turn, and
- * `profile remove` is holding the name of the one being deleted. Passing it
- * makes "which profile's manifests" a question the caller has already answered.
+ * No profile parameter any more. Manifests moved to the workspace with the
+ * connections they describe (ADR-057), so "which profile's manifests" stopped
+ * being a question — and with it the whole reason `deploy` had to rebuild a
+ * registry per profile to collect credential refs.
  */
 export async function buildRegistryWithWorkspace(
   root: string,
-  profile: string,
   owner: OwnerLayerOptions = {},
 ): Promise<ProviderRegistry> {
   const skills =
     owner.skills ?? (owner.skillStore ? await loadProfileSkills(owner.skillStore) : []);
   const registry = buildRegistry({ ...owner, skills });
 
-  for (const { manifest, path } of await loadProfileProviders(root, profile)) {
+  for (const { manifest, path } of await loadWorkspaceProviders(root)) {
     if (registry.has(manifest.id)) {
       throw new ConfigError(
         `${path}: provider "${manifest.id}" is already built in. Rename it, or remove the file to use the built-in.`,

package/src/cli/runtime/select.ts

@@ -126,21 +126,12 @@ export async function resolveProfileOnly(
  * inside Google's network. Opening a full runtime for either would fail on the
  * part that is not needed.
  */
-export async function openSecretStoreFor(
-  config: Config,
-  root: string,
-  target: string,
-): Promise<SecretStore> {
+export async function openSecretStoreFor(root: string, target: string): Promise<SecretStore> {
   // Resolved here rather than taken from the caller, so `secrets push --from
   // local --to cloud` can hold two targets that live in two different workspaces
   // without the caller having to follow either pointer itself.
   const resolved = await openTarget(root, target);
-  return openSecrets({
-    declared: resolved.declared,
-    config,
-    root: resolved.workspaceRoot,
-    target,
-  });
+  return openSecrets({ declared: resolved.declared, root: resolved.workspaceRoot, target });
 }
 
 /**

package/src/cli/runtime/stores.ts

@@ -0,0 +1,58 @@
+import { layout } from '#profile';
+import type { BlobStore } from '#stores/blobs';
+import type { StorageFactory } from '#deployments/target.ts';
+
+/**
+ * Where the owner layer's bytes are, for a runtime being assembled.
+ *
+ * Split from `open.ts` so that file stays inside the size budget, on the seam
+ * it already had: `open.ts` decides what a runtime *is* and this decides where
+ * one store lives. Both roots are explicit areas rather than derived from
+ * `storage.path`, matching `openState` and `openAudit` — a workspace that moves
+ * its provider blobs does not move the reserved roots beside them.
+ */
+
+/**
+ * A store with nothing in it, for a profile that grants no skills connection.
+ *
+ * Written out rather than imported from `#stores/blobs/testing.ts`: that module
+ * exists for tests, and production code reaching into it is how a test double
+ * ends up on a real path. Five methods, none of which can fail, is cheaper than
+ * the import would be to justify.
+ */
+export const EMPTY_SKILL_STORE: BlobStore = {
+  get: async () => null,
+  put: async () => {
+    throw new Error('this profile grants no skills connection');
+  },
+  has: async () => false,
+  delete: async () => {},
+  list: async () => [],
+};
+
+/**
+ * Where a connection's skills live, in either workspace.
+ *
+ * `profiles/<profile>/skills.d/<connection>/`, and deployed the same key under
+ * the bucket prefix. Going through the store rather than a filesystem path is what gives a
+ * deployment skills at all — a path is baked into a container image at build
+ * time and an object key is not, so before ADR-014 a deployed instance could
+ * only ever serve the skills that existed when its image was built.
+ *
+ * **Per profile and per connection**, which is the fourth answer this question
+ * has had. Policy gating `skills.<name>` was the whole isolation story while
+ * the bytes were shared (ADR-012 §1), and it is a weak one: it decides who may
+ * *run* a procedure, not who may read that it exists or what it says. ADR-030
+ * made the bytes per profile; ADR-059 made them per connection instead, so two
+ * profiles granting one skills connection shared a set; ADR-066 puts the
+ * profile back in front of it, so they do not. The connection stays because a
+ * profile may still hold more than one set.
+ */
+export function skillStore(
+  storage: StorageFactory,
+  profile: string,
+  connection: string,
+): BlobStore {
+  return storage(layout.skills(profile, connection));
+}
+

package/src/cli/runtime/types.ts

@@ -0,0 +1,106 @@
+import type { BearerAuthenticator } from '#auth';
+import type { SecretStore } from '#secrets';
+import type { AuditReader } from '#audit';
+import type { RuntimeState } from '#stores/state';
+import type { BlobStore } from '#stores/blobs';
+import type { AnyConnector, ProviderManifest } from '#connectivity';
+import type {
+  Config,
+  ConnectionConfig,
+  Resolution,
+  SelectedConnection,
+  TargetConfig,
+} from '#profile';
+import type { ProviderRegistry } from '#registry';
+import type { Dispatcher } from '#dispatch';
+import type { VaultStore } from '#providers/owner.ts';
+import type { KnowledgeStores } from '#deployments/knowledge.ts';
+
+/**
+ * What a command is handed once a profile has been opened.
+ *
+ * Its own file so `open.ts` stays inside the size budget, and because this is
+ * the thing every command in the CLI is written against — a reader looking for
+ * "what do I get" should not have to read the assembly to find it.
+ */
+
+export interface Runtime {
+  readonly resolution: Resolution;
+  readonly config: Config;
+  readonly target: string;
+  /**
+   * The target's adapter set, from the workspace that declares it.
+   *
+   * Here because the config no longer carries it. Every caller that used to
+   * reach `config.targets[target]` — for a `deploy` block, a storage adapter, a
+   * knowledge repository — reads this instead, and reads it without following
+   * the pointer a second time (ADR-052).
+   */
+  readonly declared: TargetConfig;
+  /**
+   * The accounts this profile selects, joined to the grants that govern them.
+   *
+   * The join is done once, here, because everything that asks — status, doctor,
+   * reconcile, setup — wants the same answer and three implementations of it is
+   * three chances to disagree (`profile/connections.ts`).
+   */
+  readonly connections: readonly SelectedConnection[];
+  /** Every account the workspace holds, granted or not. `connection list` reads this. */
+  readonly workspaceConnections: readonly ConnectionConfig[];
+  /** Vendors this workspace registered a client of its own for (`oauth_apps`). */
+  readonly ownClients: readonly string[];
+  readonly state: RuntimeState;
+  /** The durable log, for reading. Copies, if any, are write-only and not here. */
+  readonly audit: AuditReader;
+  readonly credentials: SecretStore;
+  readonly storage: BlobStore;
+  /**
+   * Where this profile's skills are kept — `data/skills.d/<connection>/` locally.
+   *
+   * `undefined` when the profile grants no `skills` connection. That is a real
+   * state rather than an empty one, and it is worth the optionality: the owner
+   * layer arrives granted (ADR-050), so a profile without it was denied it on
+   * purpose, and handing back an empty store would report "no skills" for a
+   * profile that is not allowed to have any — the same answer for two different
+   * facts.
+   */
+  readonly skills: BlobStore | undefined;
+  /**
+   * Present only when this target keeps memory and skills in a repository.
+   *
+   * Nothing on the dispatch path reads it: `storage` and `skills` above are
+   * already pointed at the right bytes, which is the whole design. It is here
+   * so `target show` and `doctor` can say where those bytes are without
+   * re-reading the config, and so the migration can reach the repository it is
+   * committing to.
+   */
+  readonly knowledge?: KnowledgeStores | undefined;
+  /** The vault's own store, so `lanes link vault` reaches the same bytes MCP does. */
+  readonly vault: VaultStore;
+  readonly registry: ProviderRegistry;
+  /**
+   * Re-read the skills into the registry when they have changed on the store.
+   *
+   * Cheap and idempotent — one `list()`, and a rebuild only when the listing
+   * differs from the last one. The caller decides how often to ask.
+   */
+  refreshSkills(): Promise<void>;
+  readonly dispatcher: Dispatcher;
+  readonly authenticator: BearerAuthenticator;
+  /** Same factory the dispatcher uses, exposed for commands that probe upstream. */
+  connectorFor(providerId: string, connectionId: string): AnyConnector | undefined;
+  /**
+   * Same authorizer the dispatcher uses, for the same reason `connectorFor` is here.
+   *
+   * A command that probes upstream needs the credential on the request, and it
+   * must not learn how to put it there — that is one switch on the resolved
+   * shape (`connectivity/auth/authorize.ts`) and a second copy would be a
+   * second answer. `settleIdentity` is the caller: it asks a provider whose
+   * account was just authorised, over whatever method that provider declares.
+   */
+  authorizeRequest(providerId: string, connectionId: string, request: Request): Promise<Request>;
+  /** A provider's manifest, so an omitted `credential_ref` can be derived from it. */
+  manifestFor(providerId: string): ProviderManifest | undefined;
+  close(): Promise<void>;
+}
+

package/src/cli/runtime/vault.ts

@@ -1,4 +1,5 @@
-import { layout, workspacePath } from '#profile';
+import {
+  soleGrantFor, layout, vaultRef, workspacePath } from '#profile';
 import type { SecretStore } from '#secrets';
 import {
   createBlobVaultStore,
@@ -36,10 +37,15 @@ export function openVault(
   const { declared, config, root } = input;
   const vault = declared.vault ?? { adapter: 'file' as const };
 
+  // The vault connection this profile grants (ADR-059). `main` when it grants
+  // none, which keeps a profile that denied the vault opening against the same
+  // document every other profile uses rather than inventing a second one.
+  const connection = soleGrantFor(config, 'lanes_vault') ?? 'main';
+
   switch (vault.adapter) {
     case 'file':
       return createFileVaultStore({
-        path: workspacePath(root, vault.path ?? layout.vault(config.instance.profile)),
+        path: workspacePath(root, vault.path ?? layout.vault(config.instance.profile, connection)),
       });
 
     case 'secret':
@@ -47,15 +53,24 @@ export function openVault(
       // so the credential store holds ciphertext it cannot read. Separate
       // document, separate key, separate environment variable — the backend
       // was never what kept the two stores apart. ADR-022.
+      //
+      // Named per connection, like the file adapter. A `ref` written by hand
+      // still wins, because a deployment that already seals under one name has
+      // to keep opening it — but the default carries the instance, so two
+      // profiles granting different vaults share nothing. Without this only
+      // `file` honoured ADR-059 and every deployed workspace, which uses this
+      // adapter or `blob`, had one document behind every vault connection:
+      // ADR-059 calls that the worst of the three collisions, because the wrong
+      // answer is a credential.
       return createSecretVaultStore({
         store: credentials,
-        ...(vault.ref !== undefined ? { ref: vault.ref } : {}),
+        ref: vaultRef(declared, config),
       });
 
     case 'blob':
       return createBlobVaultStore({
         store: storage(),
-        ...(vault.path !== undefined ? { key: vault.path } : {}),
+        key: vault.path ?? layout.vaultKey(connection),
       });
   }
 }

package/src/cli/runtime/workspace.ts

@@ -0,0 +1,60 @@
+import { ConfigError, listProfiles, openTarget, resolveWorkspaceRoot } from '#profile';
+import { openRuntime, type Runtime } from './open.ts';
+import type { GlobalFlags } from './select.ts';
+
+/**
+ * A runtime for a workspace, when the command does not act on one profile.
+ *
+ * Contract 3 moved the credential store, the audit log, the state store and the
+ * blob root up to the workspace, so a command that opens any of them opens the
+ * same thing whichever profile it was handed. `openRuntime` still wants one,
+ * because a `Runtime` carries a resolved profile — so this picks one rather
+ * than making the caller ask a question with no answer.
+ *
+ * `--profile` still narrows where narrowing means something: the audit log is
+ * one chain and the flag filters it, rather than selecting which log to read.
+ * What it must never do is *decide* anything, which is why the profile chosen
+ * here when none is given is simply the first and is never reported as though
+ * it were the subject.
+ */
+export async function openWorkspaceRuntime(flags: GlobalFlags): Promise<Runtime> {
+  if (flags.profile !== undefined) return openRuntime(flags);
+
+  const root = resolveWorkspaceRoot();
+  const resolved = await openTarget(root, flags.target!);
+  const names = await listProfiles(resolved.workspaceRoot);
+
+  if (names.length === 0) {
+    throw new ConfigError(
+      `Workspace "${flags.target}" holds no profiles, so there is nothing to open.\n` +
+        `  Create one with: lanes link profile add <name> --workspace ${flags.target}`,
+    );
+  }
+
+  return openRuntime({ ...flags, profile: names[0]! });
+}
+
+/**
+ * Which profile a workspace-level command should act *as*.
+ *
+ * Distinct from `openWorkspaceRuntime` because the caller needs the name rather
+ * than a runtime — `start` puts it back into flags and hands them on. Same rule:
+ * `--profile` wins, and otherwise the first is taken without being reported as
+ * a choice, because for the things this is used for it is not one.
+ */
+export async function primaryProfile(flags: GlobalFlags): Promise<string> {
+  if (flags.profile !== undefined) return flags.profile;
+
+  const root = resolveWorkspaceRoot();
+  const resolved = await openTarget(root, flags.target!);
+  const names = await listProfiles(resolved.workspaceRoot);
+
+  if (names.length === 0) {
+    throw new ConfigError(
+      `Workspace "${flags.target}" holds no profiles, so there is nothing to serve.\n` +
+        `  Create one with: lanes link profile add <name> --workspace ${flags.target}`,
+    );
+  }
+
+  return names[0]!;
+}

package/src/cli/runtime.ts

@@ -32,4 +32,5 @@ export {
   type OwnerLayerOptions,
 } from './runtime/registry.ts';
 
-export { openRuntime, type OpenOptions, type Runtime } from './runtime/open.ts';
+export { grantedConnections, openRuntime, type OpenOptions, type Runtime } from './runtime/open.ts';
+export { openWorkspaceRuntime, primaryProfile } from './runtime/workspace.ts';