@gaia-ai/conductor 0.9.2 → 0.11.0

package/dist/src/cli/config-schema.d.ts

@@ -43,11 +43,60 @@ export declare const RENDERER_PLUGIN_ENTRY = "{ plugin: '@gaia-ai/addon-essentia
  * hand-reshaped file) is left alone rather than guessed at.
  */
 export declare function addRendererPluginEntry(text: string): string;
+/** The dropsh plugin package whose entries carry a connection's OAuth identity. */
+export declare const OAUTH2_PLUGIN_PACKAGE = "@dropsh/plugin-oauth2";
+/**
+ * The id of the ONE oauth2 provider a GAIA connection declares (GAIA-391 D1).
+ *
+ * `gaia`, not `session`: the entry names the CONNECTION, not a capability. Until
+ * v3 a config declared two providers that differed only by scope — `session`
+ * (`gaia:session`) and `pm` (`gaia:project_manager`) — and every write had to
+ * pick one. What that choice cost is what GAIA-391 removes; the id therefore
+ * names the connection, and the surviving scope carries the capability.
+ */
+export declare const OAUTH2_PROVIDER_ID = "gaia";
+/**
+ * The ONE OAuth2 scope a GAIA connection requests (GAIA-391 D1, as revised).
+ *
+ * There is exactly one, and there is not zero. `gaia:project_manager` is
+ * retired; `gaia:session` survives and its role carries the ceiling of what a
+ * machine identity may do.
+ *
+ * Zero was the original design, and a live control plane refuted it:
+ * `simple_oauth`'s Oauth2AccessPolicy rewrites a token account's permissions
+ * with `overwrite: TRUE`, and for a `client_credentials` token — every GAIA
+ * machine identity — the set becomes EXACTLY the scope's permissions, with
+ * neither user_role nor OG-rank permissions surviving. A request naming no scope
+ * against a consumer holding no default scopes does not even mint a token.
+ */
+export declare const OAUTH2_SCOPE = "gaia:session";
+/**
+ * GAIA-391 (v2 → v3): collapse a connection's oauth2 entries into ONE `gaia`
+ * provider on ONE scope — the whole of the one-identity change, as a pure text
+ * transform.
+ *
+ * A MIGRATION rather than a cutover (spec D3): operators have hand-edited these
+ * files — a pinned literal `baseUrl`, a per-install `workspace_id`, an extra
+ * `addons[]` entry — so every value outside the two elements being merged is
+ * carried over verbatim, and the runner never EXECUTES a possibly
+ * side-effecting config module.
+ *
+ * The FIRST oauth2 element survives (it is the one v2 marked `default: true`);
+ * the rest are removed line-and-all. A config with no oauth2 element is left
+ * exactly as it is — that is the one silent no-op, and it is silent because
+ * there is nothing to collapse. An element that IS there but cannot be given the
+ * `gaia` identity throws (see {@link ensureProviderId}) rather than passing
+ * through unchanged.
+ */
+export declare function collapseOauth2Providers(text: string): string;
 /**
  * The ordered, contiguous migration chain. v1 was the pre-GAIA-226 shape (auth
- * plugins only); v2 adds the markdown renderer entry. Nothing below v1 is a
- * versioned config (v0 = seed / hand-authored / untouched). `GAIA_CONFIG_SCHEMA_VERSION`
- * derives from the chain's last `to` — never hardcode it.
+ * plugins only); v2 adds the markdown renderer entry; v3 collapses the two
+ * differently-scoped oauth2 providers into ONE identity on ONE scope (GAIA-391)
+ * — one, not zero: see {@link OAUTH2_SCOPE} for why the scope survives.
+ * Nothing below v1 is a versioned config (v0 = seed / hand-authored / untouched).
+ * `GAIA_CONFIG_SCHEMA_VERSION` derives from the chain's last `to` — never
+ * hardcode it.
  */
 export declare const CONNECTION_MIGRATIONS: ConnectionConfigMigration[];
 /** The current connection-config schema version — single source of truth. */

package/dist/src/cli/config-schema.js

@@ -27,6 +27,19 @@ export const RENDERER_PLUGIN_ENTRY = `{ plugin: '${RENDERER_PLUGIN_PACKAGE}' },`
 const PLUGINS_ARRAY_OPEN_RE = /^([ \t]*)plugins:\s*\[[ \t]*$/m;
 /** Whole-line `//` comments — stripped before the presence probe (see below). */
 const LINE_COMMENT_RE = /^[ \t]*\/\/.*$/gm;
+/**
+ * Blank out whole-line `//` comments WITHOUT moving a single byte.
+ *
+ * `addRendererPluginEntry` can simply delete them, because it only asks a
+ * yes/no question. The v2→v3 collapse below needs OFFSETS into the real text,
+ * so a comment has to become the same number of spaces rather than disappear:
+ * the shipped connection config explains itself in prose that names both
+ * `@dropsh/plugin-oauth2` and a `{ site, plugins }` shape, and a scan that read
+ * those as code would splice a comment fragment.
+ */
+function maskLineComments(text) {
+    return text.replace(LINE_COMMENT_RE, (line) => ' '.repeat(line.length));
+}
 /**
  * GAIA-226 (v1 → v2): insert the renderer aggregator as the FIRST `plugins[]`
  * element, so `gaia dropsh --format md` works instead of failing with
@@ -49,11 +62,219 @@ export function addRendererPluginEntry(text) {
     const indent = `${m[1]}  `;
     return text.replace(PLUGINS_ARRAY_OPEN_RE, (line) => `${line}\n${indent}${RENDERER_PLUGIN_ENTRY}`);
 }
+/** The dropsh plugin package whose entries carry a connection's OAuth identity. */
+export const OAUTH2_PLUGIN_PACKAGE = '@dropsh/plugin-oauth2';
+/**
+ * The id of the ONE oauth2 provider a GAIA connection declares (GAIA-391 D1).
+ *
+ * `gaia`, not `session`: the entry names the CONNECTION, not a capability. Until
+ * v3 a config declared two providers that differed only by scope — `session`
+ * (`gaia:session`) and `pm` (`gaia:project_manager`) — and every write had to
+ * pick one. What that choice cost is what GAIA-391 removes; the id therefore
+ * names the connection, and the surviving scope carries the capability.
+ */
+export const OAUTH2_PROVIDER_ID = 'gaia';
+/**
+ * The ONE OAuth2 scope a GAIA connection requests (GAIA-391 D1, as revised).
+ *
+ * There is exactly one, and there is not zero. `gaia:project_manager` is
+ * retired; `gaia:session` survives and its role carries the ceiling of what a
+ * machine identity may do.
+ *
+ * Zero was the original design, and a live control plane refuted it:
+ * `simple_oauth`'s Oauth2AccessPolicy rewrites a token account's permissions
+ * with `overwrite: TRUE`, and for a `client_credentials` token — every GAIA
+ * machine identity — the set becomes EXACTLY the scope's permissions, with
+ * neither user_role nor OG-rank permissions surviving. A request naming no scope
+ * against a consumer holding no default scopes does not even mint a token.
+ */
+export const OAUTH2_SCOPE = 'gaia:session';
+/**
+ * Every `plugins[]` element that names {@link OAUTH2_PLUGIN_PACKAGE}, in order.
+ *
+ * Brace-balanced from the `{` that opens the element (the package name is the
+ * first key of every entry the scaffold and the migrations write) to its match,
+ * absorbing the trailing comma so an element can be removed whole. Comments are
+ * MASKED, not stripped, so these offsets index the real text.
+ *
+ * A `${…}` inside a template literal is brace-balanced too, which is why
+ * `token_url: \`${baseUrl}/oauth/token\`` needs no special case. An UNBALANCED
+ * file yields nothing at all rather than a guessed span — the migration then
+ * leaves it untouched, which is the same refusal `addRendererPluginEntry` makes
+ * for a config with no `plugins: [` literal.
+ */
+function oauth2EntrySpans(text) {
+    const probe = maskLineComments(text);
+    const spans = [];
+    let from = 0;
+    for (;;) {
+        const hit = probe.indexOf(OAUTH2_PLUGIN_PACKAGE, from);
+        if (hit === -1)
+            return spans;
+        const start = probe.lastIndexOf('{', hit);
+        if (start === -1) {
+            from = hit + OAUTH2_PLUGIN_PACKAGE.length;
+            continue;
+        }
+        let depth = 0;
+        let i = start;
+        for (; i < probe.length; i += 1) {
+            if (probe[i] === '{')
+                depth += 1;
+            else if (probe[i] === '}') {
+                depth -= 1;
+                if (depth === 0) {
+                    i += 1;
+                    break;
+                }
+            }
+        }
+        if (depth !== 0)
+            return [];
+        let end = i;
+        while (probe[end] === ' ' || probe[end] === '\t')
+            end += 1;
+        if (probe[end] === ',')
+            end += 1;
+        spans.push({ start, end });
+        from = end;
+    }
+}
+/** Grow a span to its whole line, when the line holds nothing else. */
+function wholeLineSpan(text, span) {
+    const lineStart = text.lastIndexOf('\n', span.start) + 1;
+    const start = text.slice(lineStart, span.start).trim() === '' ? lineStart : span.start;
+    const newline = text.indexOf('\n', span.end);
+    const end = newline !== -1 && text.slice(span.end, newline).trim() === ''
+        ? newline + 1
+        : span.end;
+    return { start, end };
+}
+const SCOPE_VALUE = /(?:'[^']*'|"[^"]*")/.source;
+/** Every `scope: '…'`, for rewriting the VALUE in place. */
+const SCOPE_KEY_RE = new RegExp(`(\\bscope:\\s*)${SCOPE_VALUE}`, 'g');
+/** Whether the element names a scope at all. Non-global: `.test` must not seek. */
+const SCOPE_PRESENT_RE = new RegExp(`\\bscope:\\s*${SCOPE_VALUE}`);
+const ID_LINE_RE = /^([ \t]*)id:\s*'[^']*',[ \t]*\r?\n/m;
+const ID_INLINE_RE = /\bid:\s*'[^']*',/;
+/** Whether the element names an id at all — no trailing comma required. */
+const ID_PRESENT_RE = /\bid:\s*'[^']*'/;
+/** `with: {` as the last thing on its line — the fallback insertion anchor. */
+const WITH_LINE_RE = /^([ \t]*)with:\s*\{[ \t]*\r?\n/m;
+/** `with: {` anywhere — the same anchor for a single-line `with: { … }`. */
+const WITH_INLINE_RE = /\bwith:\s*\{/;
+/**
+ * Ensure the element names {@link OAUTH2_PROVIDER_ID} as its provider id.
+ *
+ * The id is also the ANCHOR the two other v3 edits insert against, so resolving
+ * it first is what makes them reachable. An element that already names an id has
+ * that value rewritten; one that names none gets the key inserted at the head of
+ * its `with: { … }` block.
+ *
+ * An element with neither THROWS. That is the GAIA-391 round-2 correction: the
+ * first round used the `id:` key as its only anchor and simply returned such an
+ * element verbatim, so `gaia upgrade` re-stamped the file to v3 and reported
+ * success while leaving a provider dropsh cannot resolve — no id to select it by
+ * and no `default: true` to make it the fallback, i.e. a config that mints
+ * nothing. Silent success on a config that was not migrated is worse than a
+ * refusal the operator can act on, and the runner has already written the
+ * `.v<N>.bak` before this point, so the original is never lost.
+ */
+function ensureProviderId(entry) {
+    if (ID_PRESENT_RE.test(entry)) {
+        return entry.replace(/(\bid:\s*)'[^']*'/, `$1'${OAUTH2_PROVIDER_ID}'`);
+    }
+    const lineForm = entry.replace(WITH_LINE_RE, (line, indent) => `${line}${indent}  id: '${OAUTH2_PROVIDER_ID}',\n`);
+    if (lineForm !== entry)
+        return lineForm;
+    const inlineForm = entry.replace(WITH_INLINE_RE, (open) => `${open} id: '${OAUTH2_PROVIDER_ID}',`);
+    if (inlineForm !== entry)
+        return inlineForm;
+    throw new Error(`cannot migrate a ${OAUTH2_PLUGIN_PACKAGE} entry that names neither an ` +
+        `\`id:\` key nor a \`with: { … }\` block: there is nowhere to put the ` +
+        `single '${OAUTH2_PROVIDER_ID}' identity. Give the entry a ` +
+        `\`with: { id: '${OAUTH2_PROVIDER_ID}', scope: '${OAUTH2_SCOPE}', … }\` ` +
+        `block by hand, then re-run \`gaia upgrade\`.`);
+}
+/**
+ * Rewrite ONE oauth2 element into the single `gaia` provider.
+ *
+ * Three edits, each idempotent on already-collapsed text: the id becomes
+ * {@link OAUTH2_PROVIDER_ID} (inserted when the element names none — see
+ * {@link ensureProviderId}, which refuses loudly when it cannot be placed); the
+ * scope is normalised to the one surviving scope {@link OAUTH2_SCOPE}, and ADDED
+ * when the element names none; and `default: true` is asserted, because with one
+ * provider the resolver must be able to pick it with no profile argument.
+ *
+ * The scope is kept rather than deleted, and that is the correction GAIA-391
+ * measured rather than assumed. `simple_oauth`'s Oauth2AccessPolicy rewrites a
+ * token account's permissions with `overwrite: TRUE`, and for a
+ * `client_credentials` token the result is EXACTLY the scope's permissions — so
+ * a scopeless config either fails to mint at all (`invalid_request`, hint
+ * `Check the scope parameter`) or silently inherits whatever the consumer's
+ * default scopes happen to be. The rank still decides WHICH rows are reachable;
+ * the scope decides which operations exist at all.
+ */
+function collapseOauth2Entry(entry) {
+    let out = ensureProviderId(entry);
+    if (SCOPE_PRESENT_RE.test(out)) {
+        out = out.replace(SCOPE_KEY_RE, `$1'${OAUTH2_SCOPE}'`);
+    }
+    else {
+        const lineForm = out.replace(ID_LINE_RE, (line, indent) => `${line}${indent}scope: '${OAUTH2_SCOPE}',\n`);
+        out =
+            lineForm !== out
+                ? lineForm
+                : out.replace(ID_INLINE_RE, (id) => `${id} scope: '${OAUTH2_SCOPE}',`);
+    }
+    if (/\bdefault:\s*true\b/.test(out))
+        return out;
+    const lineForm = out.replace(ID_LINE_RE, (line, indent) => `${line}${indent}default: true,\n`);
+    if (lineForm !== out)
+        return lineForm;
+    return out.replace(ID_INLINE_RE, (id) => `${id} default: true,`);
+}
+/**
+ * GAIA-391 (v2 → v3): collapse a connection's oauth2 entries into ONE `gaia`
+ * provider on ONE scope — the whole of the one-identity change, as a pure text
+ * transform.
+ *
+ * A MIGRATION rather than a cutover (spec D3): operators have hand-edited these
+ * files — a pinned literal `baseUrl`, a per-install `workspace_id`, an extra
+ * `addons[]` entry — so every value outside the two elements being merged is
+ * carried over verbatim, and the runner never EXECUTES a possibly
+ * side-effecting config module.
+ *
+ * The FIRST oauth2 element survives (it is the one v2 marked `default: true`);
+ * the rest are removed line-and-all. A config with no oauth2 element is left
+ * exactly as it is — that is the one silent no-op, and it is silent because
+ * there is nothing to collapse. An element that IS there but cannot be given the
+ * `gaia` identity throws (see {@link ensureProviderId}) rather than passing
+ * through unchanged.
+ */
+export function collapseOauth2Providers(text) {
+    const spans = oauth2EntrySpans(text);
+    const first = spans[0];
+    if (first === undefined)
+        return text;
+    let out = text;
+    // From the END, so the surviving element's offsets stay valid.
+    for (const span of spans.slice(1).reverse()) {
+        const line = wholeLineSpan(out, span);
+        out = out.slice(0, line.start) + out.slice(line.end);
+    }
+    return (out.slice(0, first.start) +
+        collapseOauth2Entry(out.slice(first.start, first.end)) +
+        out.slice(first.end));
+}
 /**
  * The ordered, contiguous migration chain. v1 was the pre-GAIA-226 shape (auth
- * plugins only); v2 adds the markdown renderer entry. Nothing below v1 is a
- * versioned config (v0 = seed / hand-authored / untouched). `GAIA_CONFIG_SCHEMA_VERSION`
- * derives from the chain's last `to` — never hardcode it.
+ * plugins only); v2 adds the markdown renderer entry; v3 collapses the two
+ * differently-scoped oauth2 providers into ONE identity on ONE scope (GAIA-391)
+ * — one, not zero: see {@link OAUTH2_SCOPE} for why the scope survives.
+ * Nothing below v1 is a versioned config (v0 = seed / hand-authored / untouched).
+ * `GAIA_CONFIG_SCHEMA_VERSION` derives from the chain's last `to` — never
+ * hardcode it.
  */
 export const CONNECTION_MIGRATIONS = [
     {
@@ -62,6 +283,13 @@ export const CONNECTION_MIGRATIONS = [
         description: `add the ${RENDERER_PLUGIN_PACKAGE} renderer entry to plugins[]`,
         apply: addRendererPluginEntry,
     },
+    {
+        from: 2,
+        to: 3,
+        description: `collapse the two ${OAUTH2_PLUGIN_PACKAGE} entries into one ` +
+            `'${OAUTH2_PROVIDER_ID}' provider on scope '${OAUTH2_SCOPE}'`,
+        apply: collapseOauth2Providers,
+    },
 ];
 /** The current connection-config schema version — single source of truth. */
 export const GAIA_CONFIG_SCHEMA_VERSION = CONNECTION_MIGRATIONS.at(-1)?.to ?? 1;

package/dist/src/cli/init.d.ts

@@ -50,8 +50,10 @@ export declare function renderCommittedConfig(inputs: Pick<InitInputs, 'project'
  * The committed CONNECTION config `./.gaia/gaia.config.js` (GAIA-201). A
  * dropsh-shaped `{ site, plugins }` read by `gaia ui`, `gaia dropsh`, and the
  * conductor's auth. Reads base_url + client credentials from the user-global
- * machine context (`~/.gaia/machine.config.js`) and declares the session
- * (default) + pm oauth2 profiles.
+ * machine context (`~/.gaia/machine.config.js`) and declares the ONE default
+ * oauth2 provider, `gaia`, on the one scope `gaia:session` (GAIA-391). The
+ * scope is the capability ceiling for a client_credentials token; the rank an
+ * identity holds in a workspace decides which rows it reaches.
  */
 export declare function renderGaiaConfig(): string;
 /** The user-global machine context module: identity + connection (incl. secret). */

package/dist/src/cli/init.js

@@ -2,7 +2,7 @@ import { chmodSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { hostname } from 'node:os';
 import { dirname, join } from 'node:path';
 import { machineContextPath, readMachineContext, } from '@gaia-ai/core';
-import { GAIA_CONFIG_SCHEMA_VERSION, RENDERER_PLUGIN_ENTRY, } from './config-schema.js';
+import { GAIA_CONFIG_SCHEMA_VERSION, OAUTH2_PROVIDER_ID, OAUTH2_SCOPE, RENDERER_PLUGIN_ENTRY, } from './config-schema.js';
 export { machineContextPath, readMachineContext };
 /** JS single-quoted string literal for a trusted, simple value. */
 function q(value) {
@@ -56,16 +56,17 @@ async function loadLocal() {
 const machine = await loadMachine();
 const local = await loadLocal();
 const project = local.project ?? ${q(inputs.project)};
-const composedMachineId =
+const composedConductorId =
   machine.user_id && machine.machine_id
     ? \`\${machine.user_id}-\${machine.machine_id}-\${project}\`
     : undefined;
 
 export default {
   project,
-  machine_id: local.machine_id ?? composedMachineId,
+  // Registration key (GAIA-353 renamed from machine_id). Host capacity lives on
+  // machine.config.js as max_parallel — do not set max_parallel here.
+  conductor_id: local.conductor_id ?? local.machine_id ?? composedConductorId,
   states: ['spec', 'diagnose', 'coding', 'review'],
-  max_parallel: 5,
   // Lifecycle hooks are executor-owned (GAIA-84): they live at the config top
   // level — NOT on a plugin descriptor's \`with.hooks\`.
   hooks: { after_create: 'ddev init-worktree', after_done: 'ddev delete -Oy' },
@@ -88,8 +89,10 @@ export default {
  * The committed CONNECTION config `./.gaia/gaia.config.js` (GAIA-201). A
  * dropsh-shaped `{ site, plugins }` read by `gaia ui`, `gaia dropsh`, and the
  * conductor's auth. Reads base_url + client credentials from the user-global
- * machine context (`~/.gaia/machine.config.js`) and declares the session
- * (default) + pm oauth2 profiles.
+ * machine context (`~/.gaia/machine.config.js`) and declares the ONE default
+ * oauth2 provider, `gaia`, on the one scope `gaia:session` (GAIA-391). The
+ * scope is the capability ceiling for a client_credentials token; the rank an
+ * identity holds in a workspace decides which rows it reaches.
  */
 export function renderGaiaConfig() {
     return `// @gaia-schema-version ${GAIA_CONFIG_SCHEMA_VERSION}
@@ -121,37 +124,45 @@ const local = await loadLocal();
 const baseUrl = local.base_url ?? machine.base_url;
 const clientId = local.oauth?.client_id ?? machine.client_id ?? 'gaia-agent';
 const clientSecret = local.oauth?.client_secret ?? machine.client_secret;
+// GAIA-351: the ambient workspace every create is bound to. REQUIRED — see the
+// top-level \`workspace_id\` below.
+const workspaceId = local.workspace_id ?? machine.workspace_id;
 
 export default {
   // GAIA-216: the connection-config schema version — kept in sync with the
   // header marker above so \`gaia upgrade\` can migrate a stale-shape config.
   schema_version: ${GAIA_CONFIG_SCHEMA_VERSION},
   site: { base_url: baseUrl, jsonapi_prefix: local.jsonapi_prefix ?? '/jsonapi' },
+  // GAIA-351: REQUIRED, and top-level — a sibling of \`site\`, never a member of
+  // it and never an addon's \`with\`. The filler that consumes it ships inside
+  // \`@gaia-ai/addon-essentials\`, which takes no options, so this is the only
+  // place a connection ever names its workspace. \`loadGaiaConfig\` refuses a
+  // config without it, so set \`workspace_id\` in ~/.gaia/machine.config.js (or
+  // this repo's conductor.config.local.js) to the uuid of the gaia_workspace
+  // this checkout creates into.
+  workspace_id: workspaceId,
   plugins: [
     ${RENDERER_PLUGIN_ENTRY}
+    // GAIA-391: ONE identity, on ONE scope. There used to be two entries here
+    // that differed only by the scope they requested, and every write had to
+    // pick one — that choice is what went away. The id names the CONNECTION,
+    // not a capability, which is why it is not named after a job.
+    //
+    // The scope is not ceremony: for a client_credentials token simple_oauth
+    // overwrites the account's permissions with EXACTLY the scope's, so this is
+    // the ceiling of what this identity may do. The rank it holds in a workspace
+    // still decides WHICH rows it reaches.
     {
       plugin: '@dropsh/plugin-oauth2',
       export: 'oauth2Plugin',
       with: {
-        id: 'session',
+        id: '${OAUTH2_PROVIDER_ID}',
         default: true,
         type: 'oauth2_client_credentials',
         client_id: clientId,
         client_secret: clientSecret,
         token_url: \`\${baseUrl}/oauth/token\`,
-        scope: 'gaia:session',
-      },
-    },
-    {
-      plugin: '@dropsh/plugin-oauth2',
-      export: 'oauth2Plugin',
-      with: {
-        id: 'pm',
-        type: 'oauth2_client_credentials',
-        client_id: clientId,
-        client_secret: clientSecret,
-        token_url: \`\${baseUrl}/oauth/token\`,
-        scope: 'gaia:project_manager',
+        scope: '${OAUTH2_SCOPE}',
       },
     },
   ],
@@ -160,18 +171,22 @@ export default {
 }
 /** The user-global machine context module: identity + connection (incl. secret). */
 export function renderMachineContext(ctx) {
+    const maxParallel = ctx.max_parallel ?? 1;
     return `// User-global GAIA machine context — gitignored, user-only (chmod 0600), never
 // committed. A plain importable module holding your machine identity +
 // connection, incl. the OAuth client secret. The engine conductor.config.js
-// composes machine_id (\`\${user_id}-\${machine_id}-\${project}\`) from it; the
-// connection gaia.config.js reads base_url / client_id / client_secret. Created
-// and gap-filled by \`gaia conductor init\`; existing values are never overwritten.
+// composes conductor_id (\`\${user_id}-\${machine_id}-\${project}\`) from it; the
+// connection gaia.config.js reads base_url / client_id / client_secret.
+// max_parallel is the host concurrent-run budget (GAIA-353) — not an engine
+// config field. Created and gap-filled by \`gaia conductor init\`; existing
+// values are never overwritten.
 export default {
   machine_id: ${q(ctx.machine_id)},
   user_id: ${q(ctx.user_id)},
   base_url: ${q(ctx.base_url)},
   client_id: ${q(ctx.client_id)},
   client_secret: ${q(ctx.client_secret)},
+  max_parallel: ${maxParallel},
 };
 `;
 }
@@ -189,6 +204,7 @@ export async function scaffoldMachineContext(opts) {
         base_url: opts.baseUrl,
         client_id: opts.clientId,
         client_secret: opts.secret,
+        max_parallel: 1,
     };
     const filledKeys = [];
     const merged = { ...derived, ...existing };
@@ -205,6 +221,12 @@ export async function scaffoldMachineContext(opts) {
             filledKeys.push(key);
         }
     }
+    if (typeof existing.max_parallel !== 'number' ||
+        !Number.isFinite(existing.max_parallel) ||
+        (existing.max_parallel ?? 0) < 1) {
+        merged.max_parallel = 1;
+        filledKeys.push('max_parallel');
+    }
     const created = !existsSync(opts.path);
     if (filledKeys.length > 0 || created) {
         mkdirSync(dirname(opts.path), { recursive: true });

package/dist/src/commands/conductor.js

@@ -4,6 +4,7 @@ import { createInterface } from 'node:readline';
 import { CommandRunner, createLogger, deriveConductorLiveness, exec, fetchUpdateNotice, loadGaiaConfig, machineContextPath, printVersionLine, readMachineContext, resolveConfigPath, setDefaultCommandRunner, signalVerifiedProcess, } from '@gaia-ai/core';
 import { Command } from 'commander';
 import { authStatus } from 'dropsh';
+import { OAUTH2_PROVIDER_ID } from '../cli/config-schema.js';
 import { scaffold } from '../cli/init.js';
 import { runUpgrade } from '../cli/upgrade.js';
 import { composeConductorConfig, loadConductorConfig } from '../config.js';
@@ -36,14 +37,14 @@ function checkoutRootOf(config) {
     return dirname(config.config_path);
 }
 /**
- * The conductor's stable identity (gaia_conductor.machine_id). machine_id is
- * required — the loader throws without it — so lifecycle commands read it here,
- * never re-derive.
+ * The conductor's stable identity (gaia_conductor.conductor_id). Required —
+ * the loader throws without it — so lifecycle commands read it here, never
+ * re-derive. Soft-reads legacy machine_id during the GAIA-353 cutover.
  */
 function conductorIdOf(config) {
-    const id = config.machine_id;
+    const id = config.conductor_id ?? config.machine_id;
     if (id === undefined || id.trim() === '') {
-        throw new Error('conductor config has no machine_id');
+        throw new Error('conductor config has no conductor_id');
     }
     return id;
 }
@@ -575,10 +576,15 @@ function registerInit(conductor) {
                     ? `updated ${m.path} (filled: ${m.filledKeys.join(', ')})`
                     : `kept ${m.path} (already complete)`);
         }
+        // GAIA-391: ONE login, because the scaffolded connection declares ONE
+        // oauth2 provider. The id is interpolated from OAUTH2_PROVIDER_ID — the
+        // same constant `renderGaiaConfig` and the v2→v3 migration emit — so
+        // this first-impression block can never name a provider the config does
+        // not have. It used to print two logins and `# both profiles present`;
+        // neither id resolved and that status line could not become true.
         console.log('\nNext steps:\n' +
-            '  gaia dropsh auth login --provider session\n' +
-            '  gaia dropsh auth login --provider pm\n' +
-            '  gaia dropsh auth status   # both profiles present');
+            `  gaia dropsh auth login --provider ${OAUTH2_PROVIDER_ID}\n` +
+            '  gaia dropsh auth status');
     });
 }
 /** The `conductor` command plugin the host mounts (GAIA-201). GAIA-224

package/dist/src/config.js

@@ -1,7 +1,7 @@
 import { readdirSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { discoverAddons, emptyContributions, findDefaultExportObject, matchDelimiter, resolveConductorSlots, resolveModuleEslintStyle, scanTopLevelProperties, } from '@gaia-ai/core';
+import { discoverAddons, emptyContributions, findDefaultExportObject, matchDelimiter, readMachineContext, resolveConductorSlots, resolveModuleEslintStyle, scanTopLevelProperties, } from '@gaia-ai/core';
 import { narrowConductorContributions } from './plugins/preset.js';
 // GAIA-201: the `.gaia/` walk-up + connection resolution moved to `@gaia-ai/core`
 // (`resolveConfigPath` / `resolveGaiaConfigPath` / `findGaiaDir`). Re-export the
@@ -187,18 +187,45 @@ export async function loadConductorConfig(configFile) {
     const states = Array.isArray(config.states)
         ? config.states.map((state) => requireNonEmptyString(state, 'states'))
         : [];
-    // machine_id is required — the config MUST set it; there is no derived
-    // fallback. The id is defined in a single place (config.machine_id), which
-    // the CLI lifecycle commands and registration all read, never re-derive. The
-    // conductor label defaults to it (a conductor is identified by it). A repo's
-    // committed config composes it from the machine context
-    // (`${user_id}-${machine_id}-${project}`); with several named configs in one
-    // .gaia/ (GAIA-126) each composes its own from its own project, so co-located
-    // conductors get distinct identities with no filename-based fallback.
-    const machineId = requireNonEmptyString(config.machine_id, 'machine_id');
+    // conductor_id is required (GAIA-353 renamed from machine_id). Prefer the new
+    // key; accept legacy machine_id with a one-shot warning. No derived fallback.
+    // A repo's committed config composes it from the machine context
+    // (`${user_id}-${host}-${project}`); co-located configs each compose their
+    // own from their project.
+    let conductorId;
+    if (typeof config.conductor_id === 'string' &&
+        config.conductor_id.trim() !== '') {
+        conductorId = config.conductor_id.trim();
+    }
+    else if (typeof config.machine_id === 'string' &&
+        config.machine_id.trim() !== '') {
+        console.warn(`[gaia] ${configPath}: engine key "machine_id" is deprecated; use "conductor_id" (GAIA-353)`);
+        conductorId = config.machine_id.trim();
+    }
+    else {
+        throw new Error(`conductor config requires non-empty conductor_id (legacy machine_id accepted)`);
+    }
     const label = typeof config.label === 'string' && config.label.trim() !== ''
         ? config.label
-        : machineId;
+        : conductorId;
+    // Capacity SoT is the machine context (GAIA-353). Engine max_parallel is
+    // ignored with a warning so leftover configs do not reintroduce a per-process
+    // private quota.
+    if (config.max_parallel !== undefined) {
+        console.warn(`[gaia] ${configPath}: engine "max_parallel" is ignored; set max_parallel on ~/.gaia/machine.config.js (GAIA-353)`);
+    }
+    const machineCtx = await readMachineContext();
+    const maxParallel = typeof machineCtx.max_parallel === 'number' &&
+        Number.isFinite(machineCtx.max_parallel) &&
+        machineCtx.max_parallel >= 1
+        ? Math.floor(machineCtx.max_parallel)
+        : 1;
+    // Host stem for gaia_machine / registration (GAIA-353) — prefer the machine
+    // context id over hyphen-splitting the composed conductor_id.
+    const hostKey = typeof machineCtx.machine_id === 'string' &&
+        machineCtx.machine_id.trim() !== ''
+        ? machineCtx.machine_id.trim()
+        : undefined;
     // GAIA-215: discover the conductor `addons: []` surface (last-wins singletons,
     // agent candidate list). A pre-existing per-slot descriptor still loads and
     // WINS over a discovered contributor of the same kind (back-compat additive).
@@ -245,13 +272,16 @@ export async function loadConductorConfig(configFile) {
         agent,
         workspace,
         label,
-        machine_id: machineId,
+        conductor_id: conductorId,
+        // Soft alias so callers that still read machine_id keep working this cut.
+        machine_id: conductorId,
         project,
         states,
         prompt: typeof config.prompt === 'string' && config.prompt.trim() !== ''
             ? config.prompt
             : DEFAULT_AGENT_PROMPT,
-        max_parallel: optionalPositiveInteger(config.max_parallel, 1, 'max_parallel'),
+        max_parallel: maxParallel,
+        ...(hostKey !== undefined ? { host_key: hostKey } : {}),
         poll_interval_ms: optionalPositiveInteger(config.poll_interval_ms, 5000, 'poll_interval_ms'),
         lease_seconds: optionalPositiveInteger(config.lease_seconds, 300, 'lease_seconds'),
         ...(config.hooks !== undefined ? { hooks: config.hooks } : {}),

package/dist/src/core/conductor.d.ts

@@ -25,6 +25,12 @@ export declare class Conductor {
     private uuid;
     constructor(config: ConductorFileConfig, remote: GaiaRemote, executor: GaiaExecutor, workspace: GaiaWorkspace, agents: ResolvedAgent[], logger: ConductorLogger, checkoutRoot?: string);
     get id(): string;
+    /**
+     * Host stem for gaia_machine.host_key. Prefer config.host_key from
+     * MachineContext.machine_id; fall back to a best-effort parse of the composed
+     * conductor_id only when the loader could not supply the stem.
+     */
+    private get hostKey();
     /**
      * Whether this instance is the serve-loop process itself (GAIA-232).
      *

package/dist/src/core/conductor.js

@@ -103,7 +103,27 @@ export class Conductor {
         this.checkoutRoot = checkoutRoot;
     }
     get id() {
-        return this.config.machine_id ?? conductorId(this.checkoutRoot);
+        return (this.config.conductor_id ??
+            this.config.machine_id ??
+            conductorId(this.checkoutRoot));
+    }
+    /**
+     * Host stem for gaia_machine.host_key. Prefer config.host_key from
+     * MachineContext.machine_id; fall back to a best-effort parse of the composed
+     * conductor_id only when the loader could not supply the stem.
+     */
+    get hostKey() {
+        const fromConfig = this.config.host_key?.trim();
+        if (fromConfig)
+            return fromConfig;
+        const id = this.id;
+        const parts = id.split('-');
+        if (parts.length >= 3 && parts[0] && parts[1]) {
+            const middle = parts.slice(1, -1).join('-');
+            if (middle)
+                return middle;
+        }
+        return id;
     }
     /**
      * Whether this instance is the serve-loop process itself (GAIA-232).
@@ -130,6 +150,7 @@ export class Conductor {
     registration() {
         const base = {
             id: this.id,
+            host_key: this.hostKey,
             project: this.config.project,
             states: this.config.states,
             workspace: this.checkoutRoot,
@@ -163,15 +184,28 @@ export class Conductor {
         if (!this.uuid)
             throw new Error('not started');
         let count = await this.remote.activeRunCount(this.id);
-        // A heartbeat is the server-side self-heal: it upserts by machine_id (so it
-        // never 404s and recreates a vanished registration) and refreshes the lease
-        // — no client-side re-register, no separate status read.
+        // A heartbeat is the server-side self-heal: it upserts by conductor_id (so
+        // it never 404s and recreates a vanished registration) and refreshes the
+        // lease — no client-side re-register, no separate status read. It also
+        // recomputes gaia_machine.current_load (peers + this process's load).
         await this.remote.heartbeat(this.registration(), count, this.config.lease_seconds);
-        this.logger.info({ conductorId: this.id, active: count }, 'conductor tick');
+        // GAIA-353 D5: gate claims on the shared host budget, not only this
+        // process's active runs. After the heartbeat above, machine.current_load
+        // includes peers + self; each claim below increments the local view so
+        // pending dispatches count without a second round-trip.
+        const capacity = await this.remote.machineCapacity(this.hostKey);
+        let machineLoad = capacity?.currentLoad ?? count;
+        const maxParallel = this.config.max_parallel;
+        this.logger.info({
+            conductorId: this.id,
+            active: count,
+            machineLoad,
+            capacity: maxParallel,
+        }, 'conductor tick');
         await this.finalizeDoneRuns();
         await this.reap();
         let claimed = 0;
-        while (count < this.config.max_parallel) {
+        while (machineLoad < maxParallel) {
             const run = await this.remote.claimNext({
                 leaseSeconds: this.config.lease_seconds,
                 conductorId: this.id,
@@ -203,14 +237,16 @@ export class Conductor {
                 }
             }
             count += 1;
+            machineLoad += 1;
             claimed += 1;
         }
         if (claimed === 0) {
             this.logger.info({
                 conductorId: this.id,
                 active: count,
-                capacity: this.config.max_parallel,
-            }, count >= this.config.max_parallel
+                machineLoad,
+                capacity: maxParallel,
+            }, machineLoad >= maxParallel
                 ? 'at capacity, nothing claimed'
                 : 'idle, nothing to claim');
         }
@@ -533,6 +569,7 @@ export class Conductor {
             await this.workspace.applyOpenLayout?.(ws.path, {
                 identifier: t.identifier,
                 branch: t.branchName,
+                title: t.title,
             });
         }
         await this.executor.runHook('before_run', ws.path, { ticket: t.identifier }, env);

package/dist/src/plugins/remote.d.ts

@@ -1,5 +1,8 @@
 export interface ConductorRegistration {
+    /** Conductor process registration key (gaia_conductor.conductor_id). */
     id: string;
+    /** Host identity stem (gaia_machine.host_key / MachineContext.machine_id). */
+    host_key?: string;
     project: string;
     /** Empty = serve all claimable states in the project (GAIA-207). */
     states: string[];
@@ -163,6 +166,16 @@ export interface GaiaRemote {
     setConductorStatus(conductorId: string, status: 'offline' | 'online'): Promise<void>;
     listConductors(owner?: 'me'): Promise<ConductorStatus[]>;
     activeRunCount(conductorId: string): Promise<number>;
+    /**
+     * Shared host capacity for this `host_key` (gaia_machine, GAIA-353 D5).
+     * After a heartbeat that reported this process's load, `currentLoad` is the
+     * sum of online conductors on the machine (peers + self). Null when the
+     * control plane has no machine row yet — callers fall back to local count.
+     */
+    machineCapacity(hostKey: string): Promise<{
+        maxParallel: number;
+        currentLoad: number;
+    } | null>;
     fetchActiveRuns(conductorId: string): Promise<ActiveRun[]>;
     claimNext(claim: ClaimOptions): Promise<ClaimedRun | null>;
     getTicket(ticketUuid: string): Promise<Ticket>;

package/dist/src/plugins/workspace.d.ts

@@ -61,5 +61,6 @@ export interface GaiaWorkspace {
     applyOpenLayout?(path: string, ctx: {
         identifier: string;
         branch: string;
+        title: string;
     }): Promise<void>;
 }

package/dist/src/types.d.ts

@@ -5,10 +5,14 @@ export interface ConductorSettings {
     /** Default: `${project} @ ${checkoutRoot}`. */
     label: string;
     /**
-     * Stable node identity (gaia_conductor.machine_id) this process registers as.
-     * Defaults to a hash of hostname + checkout path. Set it to pin a conductor to
-     * a known identity — e.g. so a ticket can be pre-assigned to it (conductor
-     * assignment is the run-start trigger), which the e2e fixtures rely on.
+     * Stable conductor registration key (gaia_conductor.conductor_id). Composed
+     * as `${user_id}-${host}-${project}` from the machine context. Set it to pin
+     * a conductor to a known identity — e.g. so a ticket can be pre-assigned to
+     * it (conductor assignment is the run-start trigger).
+     */
+    conductor_id?: string;
+    /**
+     * @deprecated GAIA-353 — alias for `conductor_id` during cutover.
      */
     machine_id?: string;
     /** Project name (gaia_project.name); resolved at registration. */
@@ -26,8 +30,17 @@ export interface ConductorSettings {
      * `{state}`, `{runUuid}`. Defaults to `DEFAULT_AGENT_PROMPT`.
      */
     prompt: string;
-    /** Default: 1. */
+    /**
+     * Host concurrent-run budget. Sourced from machine context max_parallel
+     * (GAIA-353); engine-config leftovers are ignored with a warning.
+     */
     max_parallel: number;
+    /**
+     * Host identity stem (gaia_machine.host_key). Sourced from
+     * MachineContext.machine_id — not derived by hyphen-splitting conductor_id
+     * (that mis-parses when project or host segments contain hyphens).
+     */
+    host_key?: string;
     poll_interval_ms: number;
     lease_seconds: number;
     hooks?: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaia-ai/conductor",
-  "version": "0.9.2",
+  "version": "0.11.0",
   "description": "GAIA conductor engine + CLI: registers, claims tickets via JSON:API, dispatches agents.",
   "type": "module",
   "license": "MIT",
@@ -28,10 +28,10 @@
     "directory": "gaia-cli/conductor"
   },
   "dependencies": {
-    "@gaia-ai/core": "^0.9.2",
-    "@dropsh/plugin-oauth2": "^0.5.7",
-    "@dropsh/plugin-jsonapi-schema": "^0.5.8",
+    "@gaia-ai/core": "^0.11.0",
+    "@dropsh/plugin-oauth2": "^0.6.1",
+    "@dropsh/plugin-jsonapi-schema": "^0.6.1",
     "commander": "^12.1.0",
-    "dropsh": "^0.5.8"
+    "dropsh": "^0.6.1"
   }
 }