@@ -0,0 +1,13 @@
+---
+'@objectstack/cli': patch
+'@objectstack/runtime': patch
+---
+
+fix(cli,runtime): the organization-ownership refusal names the database for `os dev -d`, and the driver and token `os start` / `os dev` were given by flag
+
+Clause-②: yes (widening) — `@objectstack/runtime`'s published `OrganizationOwnershipBootGuardOptions` gains two optional members, `databaseDriver` and `databaseAuthTokenFromFlag`, and the refusal's two ceremony commands set `OS_DATABASE_DRIVER` and `OS_DATABASE_AUTH_TOKEN` in front when `--database-driver` / `--database-auth-token` chose them; `os dev`'s `--dev` commands carry `--database-url` when `-d` chose the database. What `os dev`, `os start`, `os serve` and `os migrate organization-ownership` accept or refuse is unchanged.
+Metadata-protocol: none
+
+`os dev -d URL` served the database `-d` chose, but when the organization-ownership boot guard refused it, the refusal printed `os migrate organization-ownership --dev --out PLAN` (and the `--apply` command) with no database, and `os dev`'s own line for a database it does not upgrade in place (anything that is not a local SQLite file) repeated that bare spelling. Run as printed, the ceremony planned the project's default database instead. `os dev` now hands its `serve` child the database it resolved through the same internal channel `os start` uses (#31488), so both commands read `os migrate organization-ownership --dev --database-url URL …`, a URL with a credential read from `"${OS_DATABASE_URL:?…}"` as before. `os dev`'s own line now points at the two commands the refusal names instead of spelling a bare one.
+
+`os start` and `os dev` put `--database-driver` and `--database-auth-token` in the child's environment only (`OS_DATABASE_DRIVER`, `OS_DATABASE_AUTH_TOKEN`), and the ceremony reads those two variables (it has no flag for either), so the printed commands opened the database with another driver or without its token. They now set both in front of the command: `OS_DATABASE_DRIVER=turso OS_DATABASE_AUTH_TOKEN="${OS_DATABASE_AUTH_TOKEN:?…}" os migrate organization-ownership …`. The token is never printed and never reaches the guard: the command re-exports the shell's own `OS_DATABASE_AUTH_TOKEN`, the refusal says to export it, and the shell stops with that message when it is unset. A driver or token the operator exported themselves is in their shell already and is not repeated.
@@ -42,6 +42,11 @@ import { claudeMcpAddLine, MCP_ENDPOINT_PATH } from './mcp/connect.js';
 // #12620 and #12662 protected against.
 import { describePortSource, parseRequestedPort, formatInvalidPortNotice, portFlagEnv } from '../utils/port-contract.js';
 import { applyCryptoKeyFileChannel } from '../utils/internal-crypto-key-file-channel.js';
+import {
+  ceremonyDatabaseUrl,
+  writeCeremonyConnectionChannel,
+  writeCeremonyDatabaseChannel,
+} from '../utils/internal-ceremony-database-channel.js';
 import { startDevDeployKey, type DeployKeyHandle } from '../utils/dev-deploy-key.js';
 // The ONE dev-TLS contract, shared with the `serve` child this command spawns
 // (#16804). ⛔ Nothing about certificates is declared in this file, and ⛔ no
@@ -841,6 +846,17 @@ export default class Dev extends Command {
         ...(flags['auth-secret'] ? { OS_AUTH_SECRET: flags['auth-secret'] } : {}),
       };
       applyFreshHomeChannel(localEnv, freshHome);
+      // [#31547] The database `-d` (or `--fresh`) chose is one the ceremony the
+      // ownership refusal names does not find on its own, and the driver and
+      // token the two flags above put here are not in the developer's shell:
+      // the child names them in both `--dev` commands, read from the
+      // resolution above (the one this boot serves), never re-resolved. Same
+      // channel as `os start` (#31488). `os dev` has no `--home`.
+      writeCeremonyDatabaseChannel(localEnv, ceremonyDatabaseUrl(resolvedDb, { homeFlag: undefined }));
+      writeCeremonyConnectionChannel(localEnv, {
+        databaseDriver: flags['database-driver'],
+        databaseAuthToken: flags['database-auth-token'],
+      });
       // The data key's file: the ONE answer `os start` takes too (#29934), so a
       // secret saved here reads back under `os start` over the same project —
       // and the file an earlier `os start` kept in the project is still read.
 
@@ -14,7 +14,7 @@ import { mountsAiServicePlugin, resolveAiServiceLoad, resolveOptionalPluginLoad
 import { registerInstalledPlugins } from '../utils/installed-plugins-boot.js';
 import { readInternalArtifactPath, readInternalConfigOutputPath } from '../utils/internal-artifact-channel.js';
 import { readAuthSecretFileChannel } from '../utils/internal-auth-secret-channel.js';
-import { readCeremonyDatabaseChannel } from '../utils/internal-ceremony-database-channel.js';
+import { readCeremonyConnectionChannel, readCeremonyDatabaseChannel } from '../utils/internal-ceremony-database-channel.js';
 import { compileForDevBoot, devCompilesAtBoot } from '../utils/dev-compile-at-boot.js';
 import { makeDirectorySync } from '../utils/make-directory.js';
 // The precedence's last rung — whether the cwd config takes part — decided by
@@ -4218,12 +4218,14 @@ export default class Serve extends Command {
         // persisted in its home names that file, so the ceremony runs with the
         // secret this server composes its security plugin with. A boot on a
         // database the ceremony would not find by default (`os start -d` or
-        // `--home`, #31488) names it, so the commands plan this database.
+        // `--home`, #31488; `os dev -d`, #31547) names it, so the commands plan
+        // this database, with the driver and token its parent's flags chose.
         const ceremonyDatabase = readCeremonyDatabaseChannel(process.env);
         await kernel.use(new OrganizationOwnershipBootGuardPlugin({
           dev: isDev,
           authSecretFile: readAuthSecretFileChannel(process.env),
           ...(ceremonyDatabase ? { databaseUrl: ceremonyDatabase } : {}),
+          ...readCeremonyConnectionChannel(process.env),
         }));
         trackPlugin('OrganizationOwnershipBootGuard');
       }
 
@@ -23,7 +23,11 @@ import {
 import { ServeRestartCoordinator } from '../utils/dev-restart.js';
 import { readEnvWithDeprecation } from '@objectstack/types';
 import { writeAuthSecretFileChannel } from '../utils/internal-auth-secret-channel.js';
-import { ceremonyDatabaseUrl, writeCeremonyDatabaseChannel } from '../utils/internal-ceremony-database-channel.js';
+import {
+  ceremonyDatabaseUrl,
+  writeCeremonyConnectionChannel,
+  writeCeremonyDatabaseChannel,
+} from '../utils/internal-ceremony-database-channel.js';
 import { applyCryptoKeyFileChannel } from '../utils/internal-crypto-key-file-channel.js';
 import { resolveStartHome } from '../utils/start-home.js';
 // The ONE port contract, shared with `dev` and with the `serve` child this
@@ -507,6 +511,12 @@ export default class Start extends Command {
     // child names it in both commands, read from the resolution above — the
     // one this boot serves — never re-resolved.
     writeCeremonyDatabaseChannel(localEnv, ceremonyDatabaseUrl(resolvedDb, { homeFlag: flags.home }));
+    // [#31547] The driver and the token the two flags above put in the child's
+    // environment only: the commands set them in front, the token by reference.
+    writeCeremonyConnectionChannel(localEnv, {
+      databaseDriver: flags['database-driver'],
+      databaseAuthToken: flags['database-auth-token'],
+    });
     // NODE_ENV is only forced to production when the user has not set it.
     // Allows `NODE_ENV=development objectstack start` to work for debugging.
     //
 
@@ -14,6 +14,9 @@ import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+// The telemetry sibling's resolution reaches both through dynamic imports: pay their load at collection.
+import '@objectstack/runtime';
+import '@objectstack/service-datasource';
 import {
   isOrganizationOwnershipRequiredMessage,
   ORGANIZATION_OWNERSHIP_REQUIRED_MESSAGE,
@@ -105,8 +108,10 @@ describe('os dev — the in-place upgrade of a v17-shape development database',
     expect(result.lines[0]).toBe('Refused (sys_mystery): sys_mystery carries organization_id …');
     expect(result.lines.at(-1)).toContain('nothing was changed');
     expect(result.lines.at(-1)).toContain(BACKUP());
-    // The ceremony is open (18.x step 6): the way on is running it by hand.
-    expect(result.lines.at(-1)).toContain('os migrate organization-ownership --dev');
+    // The ceremony is open (18.x step 6): the way on is running it by hand, by
+    // the commands the guard's refusal printed (#31547: they name the database).
+    expect(result.lines.at(-1)).toContain("the two commands the boot guard's refusal above names");
+    expect(result.lines.at(-1)).not.toContain('os migrate organization-ownership --dev');
     expect(result.lines.at(-1)).not.toContain('17.x');
   });
 
@@ -140,12 +145,16 @@ describe('os dev — the in-place upgrade of a v17-shape development database',
     expect(result.lines.at(-1)).toContain(`--apply --plan-file ${join(BACKUP(), 'plan.json')} --backup-taken`);
   });
 
-  it('a database that is not a local SQLite file is not upgraded in place: the ceremony is named instead', () => {
+  it('⭐ #31547: a database that is not a local SQLite file is not upgraded in place: the refusal\'s commands are pointed at, never respelled bare', () => {
     const result = upgradeDevelopmentDatabase(input(fakeRun({}), { sqliteFile: null, databaseUrl: 'postgres://db/app' }));
     expect(result.ok).toBe(false);
     expect(calls).toEqual([]);
     expect(existsSync(join(dir, 'backups'))).toBe(false);
-    expect(result.lines[0]).toContain('os migrate organization-ownership --dev');
+    // The guard's refusal names this database (`--database-url`), its driver and
+    // token; a bare `os migrate organization-ownership --dev` would plan the
+    // project's default database instead.
+    expect(result.lines[0]).toContain("the two commands the boot guard's refusal above names");
+    expect(result.lines[0]).not.toContain('os migrate organization-ownership --dev');
     expect(result.lines[0]).not.toContain('17.x');
   });
 
 
@@ -227,10 +227,15 @@ function discardedStamps(planFile: string): Array<{ object: string; rows: number
  */
 export function upgradeDevelopmentDatabase(input: DevelopmentUpgradeInput): DevelopmentUpgradeResult {
   // The way on, when os dev does not upgrade the database itself: the ceremony,
-  // run by hand (18.x step 6 opened it).
+  // run by hand (18.x step 6 opened it). [#31547] By the two commands the
+  // guard's refusal printed just above, never a second spelling of them here:
+  // those name the database this boot opened (`-d`), with its driver and
+  // token, and keep a credential out of the output; a bare
+  // `os migrate organization-ownership --dev` plans the project's default
+  // database instead.
   const manual =
-    'Run `os migrate organization-ownership --dev` (review its plan), then the same command with --apply ' +
-    '--plan-file FILE --backup-taken, and start os dev again.';
+    "Run the two commands the boot guard's refusal above names, first the plan (review it), then the apply, " +
+    'and start os dev again.';
   if (!input.sqliteFile) {
     return {
       ok: false,
 
@@ -19,11 +19,16 @@
  *  - the channel is owned by the parent: set when named, deleted otherwise.
  */
 
+import { readFileSync } from 'node:fs';
 import { describe, expect, it } from 'vitest';
 import {
+  INTERNAL_CEREMONY_AUTH_TOKEN_FROM_FLAG_ENV,
+  INTERNAL_CEREMONY_DATABASE_DRIVER_ENV,
   INTERNAL_CEREMONY_DATABASE_URL_ENV,
   ceremonyDatabaseUrl,
+  readCeremonyConnectionChannel,
   readCeremonyDatabaseChannel,
+  writeCeremonyConnectionChannel,
   writeCeremonyDatabaseChannel,
 } from './internal-ceremony-database-channel.js';
 
@@ -63,3 +68,38 @@ describe('the ceremony-database channel to the serve child', () => {
     expect(readCeremonyDatabaseChannel({ [INTERNAL_CEREMONY_DATABASE_URL_ENV]: '' })).toBeUndefined();
   });
 });
+
+describe('#31547 — the driver and the token flag, carried beside the URL', () => {
+  it('⭐ --database-driver is carried by value, --database-auth-token only as "the flag gave it": its value is never written', () => {
+    const env: NodeJS.ProcessEnv = {};
+    writeCeremonyConnectionChannel(env, { databaseDriver: 'turso', databaseAuthToken: 'tok-s3cret-31547' });
+    expect(env[INTERNAL_CEREMONY_DATABASE_DRIVER_ENV]).toBe('turso');
+    expect(env[INTERNAL_CEREMONY_AUTH_TOKEN_FROM_FLAG_ENV]).toBe('1');
+    expect(JSON.stringify(env)).not.toContain('s3cret');
+    // Shaped as the guard's options, so `serve` spreads it as it is.
+    expect(readCeremonyConnectionChannel(env)).toEqual({ databaseDriver: 'turso', databaseAuthTokenFromFlag: true });
+  });
+
+  it('is owned by the parent: no flag, no variable — an inherited copy never speaks', () => {
+    const env: NodeJS.ProcessEnv = {
+      [INTERNAL_CEREMONY_DATABASE_DRIVER_ENV]: 'pg',
+      [INTERNAL_CEREMONY_AUTH_TOKEN_FROM_FLAG_ENV]: '1',
+    };
+    writeCeremonyConnectionChannel(env, { databaseDriver: undefined, databaseAuthToken: undefined });
+    expect(INTERNAL_CEREMONY_DATABASE_DRIVER_ENV in env).toBe(false);
+    expect(INTERNAL_CEREMONY_AUTH_TOKEN_FROM_FLAG_ENV in env).toBe(false);
+    expect(readCeremonyConnectionChannel(env)).toEqual({});
+    // An empty flag value put nothing in the child's environment either (`start` / `dev` test truthiness).
+    writeCeremonyConnectionChannel(env, { databaseDriver: '', databaseAuthToken: '' });
+    expect(readCeremonyConnectionChannel(env)).toEqual({});
+  });
+
+  it('⭐ `os dev` writes both channels from its own resolution, as `os start` does: one hand-off, no second resolver', () => {
+    for (const command of ['start', 'dev']) {
+      const source = readFileSync(new URL(`../commands/${command}.ts`, import.meta.url), 'utf8');
+      expect(source, command).toMatch(/writeCeremonyDatabaseChannel\(localEnv, ceremonyDatabaseUrl\(resolvedDb, \{ homeFlag: /);
+      expect(source, command).toMatch(/writeCeremonyConnectionChannel\(localEnv, \{\s*databaseDriver: flags\['database-driver'\],\s*databaseAuthToken: flags\['database-auth-token'\],/);
+    }
+  });
+});
+
@@ -2,7 +2,7 @@
 
 /**
  * The CLI's INTERNAL parent-to-child channel for the database `os start`'s
- * ownership refusal must name (#31488).
+ * and `os dev`'s ownership refusal must name (#31488, #31547).
  *
  * `os start` resolves its database on the shared ladder
  * (`resolveProjectDatabaseUrl`, `@objectstack/runtime`) with two inputs no
@@ -20,15 +20,27 @@
  * not listed in `content/docs/deployment/environment-variables.mdx`. The
  * parent OWNS the variable in the child env: set when there is a database to
  * name, deleted otherwise, so an inherited copy never speaks for this run.
+ *
+ * `os dev` writes the same channel from its own resolution (#31547): its `-d`
+ * flag (or `--fresh`'s throwaway file) is just as invisible to the ceremony,
+ * and its refusal names the ceremony with `--dev`, which resolves the same
+ * ladder. Beside the URL, both commands carry what their `--database-driver`
+ * and `--database-auth-token` flags put in the child's environment only
+ * ({@link writeCeremonyConnectionChannel}): the driver by value, the token
+ * only as the fact that the flag supplied it.
  */
 
 import type { ResolvedProjectDatabaseUrl } from '@objectstack/runtime';
 
 export const INTERNAL_CEREMONY_DATABASE_URL_ENV = 'OS_INTERNAL_CEREMONY_DATABASE_URL';
+/** The `--database-driver` value the parent handed the child (#31547). */
+export const INTERNAL_CEREMONY_DATABASE_DRIVER_ENV = 'OS_INTERNAL_CEREMONY_DATABASE_DRIVER';
+/** `1` when `--database-auth-token` supplied the child's token (#31547); never the token itself. */
+export const INTERNAL_CEREMONY_AUTH_TOKEN_FROM_FLAG_ENV = 'OS_INTERNAL_CEREMONY_AUTH_TOKEN_FROM_FLAG';
 
 /**
- * The database the refusal must name: `os start`'s resolved URL when its `-d`
- * flag chose it, or when the file of a `--home` home is the database (the
+ * The database the refusal must name: the parent's resolved URL when its `-d`
+ * flag chose it (`os dev`'s `--fresh` file too), or when the file of a `--home` home is the database (the
  * unified default or a legacy file under that home). `undefined` when the
  * ceremony's own ladder reaches the same database: `$OS_DATABASE_URL`, the
  * project's declared datasource, or the default file of the project's
@@ -55,3 +67,36 @@ export function readCeremonyDatabaseChannel(env: NodeJS.ProcessEnv): string | un
   const url = env[INTERNAL_CEREMONY_DATABASE_URL_ENV];
   return url ? url : undefined;
 }
+
+/**
+ * Write what the ceremony needs, beside the URL, to open the database the
+ * child opens (#31547): the `--database-driver` value, and whether
+ * `--database-auth-token` supplied the token. Each is set exactly when the
+ * parent put the flag's value in the child's environment
+ * (`OS_DATABASE_DRIVER` / `OS_DATABASE_AUTH_TOKEN`), and deleted otherwise: a
+ * driver or token the operator exported is in the shell that runs the
+ * commands already. The token's value is never written here.
+ */
+export function writeCeremonyConnectionChannel(
+  env: NodeJS.ProcessEnv,
+  flags: { databaseDriver: string | undefined; databaseAuthToken: string | undefined },
+): void {
+  if (flags.databaseDriver) env[INTERNAL_CEREMONY_DATABASE_DRIVER_ENV] = flags.databaseDriver;
+  else delete env[INTERNAL_CEREMONY_DATABASE_DRIVER_ENV];
+  if (flags.databaseAuthToken) env[INTERNAL_CEREMONY_AUTH_TOKEN_FROM_FLAG_ENV] = '1';
+  else delete env[INTERNAL_CEREMONY_AUTH_TOKEN_FROM_FLAG_ENV];
+}
+
+/**
+ * Read it in the `serve` child, shaped as the guard's options
+ * (`databaseDriver`, `databaseAuthTokenFromFlag`): only the members the parent set.
+ */
+export function readCeremonyConnectionChannel(
+  env: NodeJS.ProcessEnv,
+): { databaseDriver?: string; databaseAuthTokenFromFlag?: true } {
+  const driver = env[INTERNAL_CEREMONY_DATABASE_DRIVER_ENV];
+  return {
+    ...(driver ? { databaseDriver: driver } : {}),
+    ...(env[INTERNAL_CEREMONY_AUTH_TOKEN_FROM_FLAG_ENV] === '1' ? { databaseAuthTokenFromFlag: true as const } : {}),
+  };
+}
@@ -30,7 +30,11 @@
  *   6446501014: the plan's column-drop fate accounts for the column, so the
  *   upgrade proceeds, loudly);
  * - the two columns are gone, and the marker the guard reads is verified;
- * - the copy taken before the upgrade is kept, with the columns still in it.
+ * - the copy taken before the upgrade is kept, with the columns still in it;
+ * - ⭐ #31547: the guard's refusal the refused boot printed names the database
+ *   `-d` chose in both `--dev` commands (`--database-url file:A.db`): run by
+ *   hand, as a database os dev does not upgrade in place needs them, they
+ *   plan that database and not the project's default.
  *
  * The card's reported stop (「The upgrade did not run to a report」 with no
  * cause) did not reproduce on this fixture, nor on an authentic HotCRM
@@ -248,6 +252,17 @@ describe('#26615 — `os dev` starts a development database with a stale organiz
     expect(output).toMatch(UPGRADED_READY);
   });
 
+  it('⭐ #31547: the refusal the refused boot printed names the database `-d` chose, in both --dev commands', () => {
+    const output = upgraded();
+    const named = 'os migrate organization-ownership --dev --database-url file:A.db';
+    expect(output, output.slice(-6000)).toContain(
+      `Run '${named} --out PLAN' to write and review its plan, take a backup, then run ` +
+        `'${named} --apply --plan-file PLAN --backup-taken'`,
+    );
+    // No driver or token flag was given: nothing is set in front of the command.
+    expect(output).not.toContain('OS_DATABASE_DRIVER=');
+  });
+
   it('the stamped value the drop discards is said, with its count, before the apply runs', () => {
     const output = upgraded();
     const said = output.indexOf('sys_secret: the plan drops its retired organization_id column, discarding 1 stamped value(s)');