madarx 2.17.0 → 2.18.0

package/lib/tools/adapters/browser-session.js

@@ -1,10 +1,15 @@
 /**
  * browser-session.js — native Playwright browser-interaction adapter.
  *
- * Drives a real headless Chromium so the main agent can navigate, click, type,
- * read, and screenshot pages that need JavaScript (unlike browser_navigate,
- * which is fetch + regex only). One managed persistent context is shared across
- * calls and auto-closed after an idle window so we never leak browser processes.
+ * Drives a real Chromium so the main agent can navigate, click, type, read, and
+ * screenshot pages that need JavaScript (unlike browser_navigate, which is
+ * fetch + regex only). One managed persistent context is shared across calls and
+ * auto-closed after an idle window so we never leak browser processes.
+ *
+ * Headless by default. Set MADARX_BROWSER_HEADED=1 (or true/yes/on) to open a
+ * VISIBLE window the operator can watch — it prefers the installed Chrome
+ * (channel:'chrome'), falling back to bundled Chromium. The idle auto-close
+ * (90s) still applies, so a visible window left untouched closes on its own.
  *
  * Safety posture:
  *  - Dedicated profile under DATA_DIR/browser-profile — NOT the user's personal
@@ -45,6 +50,33 @@ function cap(text) {
   return redactToolOutput(String(text ?? '').slice(0, MAX_TEXT_CHARS));
 }
 
+// Headed mode lets the operator watch the agent drive a real, visible browser.
+// Off by default so headless servers and CI stay unattended. When on, prefer the
+// operator's installed Chrome (channel:'chrome') so it looks/behaves like a real
+// browser; we transparently fall back to bundled Chromium if that channel is
+// unavailable. The persistent profile (PROFILE_DIR) is still the dedicated
+// madarX profile, never the user's personal Chrome data.
+function isHeaded() {
+  const v = String(process.env.MADARX_BROWSER_HEADED || '').trim().toLowerCase();
+  return v === '1' || v === 'true' || v === 'yes' || v === 'on';
+}
+
+async function launchContext(chromium) {
+  const headed = isHeaded();
+  const base = {
+    headless: !headed,
+    args: ['--no-sandbox', '--disable-dev-shm-usage'],
+  };
+  if (headed) {
+    try {
+      return await chromium.launchPersistentContext(PROFILE_DIR, { ...base, channel: 'chrome' });
+    } catch {
+      // Installed Chrome not found — fall back to bundled Chromium, still headed.
+    }
+  }
+  return await chromium.launchPersistentContext(PROFILE_DIR, base);
+}
+
 function touchIdleTimer() {
   if (_idleTimer) clearTimeout(_idleTimer);
   _idleTimer = setTimeout(() => { closeBrowser().catch(() => {}); }, IDLE_CLOSE_MS);
@@ -75,10 +107,7 @@ async function ensurePage() {
   }
   fs.mkdirSync(PROFILE_DIR, { recursive: true });
   try {
-    _context = await chromium.launchPersistentContext(PROFILE_DIR, {
-      headless: true,
-      args: ['--no-sandbox', '--disable-dev-shm-usage'],
-    });
+    _context = await launchContext(chromium);
   } catch (err) {
     _context = null;
     throw new Error(

package/lib/tools/adapters/github.js

@@ -65,12 +65,30 @@ function parseOwnerRepo(repo_full_name) {
 // ── Error extraction ──────────────────────────────────────────────────────────
 
 async function extractGitHubError(res) {
+  let message = `GitHub API error: ${res.status}`;
   try {
     const data = await res.json();
-    return data?.message || `GitHub API error: ${res.status}`;
+    if (data?.message) message = data.message;
   } catch {
-    return `GitHub API error: ${res.status}`;
+    // non-JSON body — keep the status-based message
   }
+
+  // Actionable guidance for the two access failures users actually hit.
+  // SAML SSO: the org requires the token to be explicitly authorized. GitHub
+  // signals this via the x-github-sso response header.
+  const sso = res.headers?.get?.('x-github-sso');
+  if (res.status === 403 && sso) {
+    const urlMatch = /url=([^;,\s]+)/i.exec(sso);
+    const where = urlMatch ? ` Authorize it here: ${urlMatch[1]}` : '';
+    return `${message} — this org requires SAML SSO authorization for your token.${where}`;
+  }
+  if (res.status === 403) {
+    return `${message} — the token is valid but lacks permission for this resource (check the fine-grained PAT's repository access / scopes, and authorize SSO if the org uses it).`;
+  }
+  if (res.status === 404) {
+    return `${message} — not found, OR your token cannot see it. A fine-grained PAT only sees repos it was explicitly granted; a classic PAT needs the 'repo' scope. Grant access to this repo/org and retry.`;
+  }
+  return message;
 }
 
 // ── Response shapers ──────────────────────────────────────────────────────────
@@ -146,12 +164,36 @@ export async function ghRepoList(input = {}, options = {}) {
   const token = requireCredential('GITHUB_TOKEN', options);
   const agentId = options.agent_id ?? null;
 
-  const url = new URL(`${GH_API}/user/repos`);
-  if (input.visibility) url.searchParams.set('visibility', String(input.visibility));
-  if (input.type) url.searchParams.set('type', String(input.type));
+  // Two listing modes:
+  //  - `org` set → GET /orgs/{org}/repos (repos owned by that org the token can
+  //    see). This is how you reach org repos you were granted access to.
+  //  - otherwise → GET /user/repos across every affiliation the token has, so
+  //    collaborator + organization_member repos show up, not just owned ones.
+  const org = input.org ? String(input.org).trim() : '';
+  let url;
+  if (org) {
+    if (!/^[A-Za-z0-9_.-]+$/.test(org)) {
+      throw new Error(`org must be a valid GitHub org/owner name, got: ${org}`);
+    }
+    url = new URL(`${GH_API}/orgs/${org}/repos`);
+    if (input.type) url.searchParams.set('type', String(input.type)); // all|public|private|forks|sources|member
+  } else {
+    url = new URL(`${GH_API}/user/repos`);
+    // Default to the full affiliation set so org/collaborator repos are listed.
+    url.searchParams.set('affiliation', String(input.affiliation || 'owner,collaborator,organization_member'));
+    if (input.visibility) url.searchParams.set('visibility', String(input.visibility));
+    // `type` and `affiliation` are mutually exclusive on /user/repos — only send
+    // `type` when the caller did not narrow by affiliation themselves.
+    if (input.type && !input.affiliation) {
+      url.searchParams.delete('affiliation');
+      url.searchParams.set('type', String(input.type));
+    }
+  }
   if (input.sort) url.searchParams.set('sort', String(input.sort));
   const perPage = Math.min(Math.max(Number(input.per_page || 30), 1), 100);
   url.searchParams.set('per_page', String(perPage));
+  const page = Math.max(Number(input.page || 1), 1);
+  if (page > 1) url.searchParams.set('page', String(page));
 
   const res = await wrapFetch('gh_repo_list', agentId)(url, {
     headers: githubHeaders(token),

package/lib/tools/adapters/skill-bridge.js

@@ -0,0 +1,146 @@
+// Skill bridge — Phase 4 of voice/main-agent unification.
+//
+// Exposes a tightly-allowlisted set of first-party gstack CLI skills (the
+// visible-browser flows: /connect-chrome, /browse, /qa-only) as ONE in-app
+// tool. The main agent (and, by extension, voice — which now shares the full
+// catalog) can drive the same real browser the operator watches live.
+//
+// SECURITY — this crosses the Claude Code CLI trust boundary, so it is the most
+// sharply gated tool in the registry:
+//   • risk_level 'irreversible_external' → the main-agent path ALWAYS creates an
+//     approval request, even in trust-mode 'auto' (never bypassable).
+//   • registry.js force-gates it on the AGENT path too (added alongside
+//     browser_harness_run), so a sub-agent on auto can never self-run it.
+//   • enabled_default:false → the owner must explicitly install it first.
+//   • Hard env kill-switch MADARX_SKILL_BRIDGE_DISABLED=1.
+//   • Only skills on SKILL_BRIDGE_ALLOWLIST may be invoked — the LLM cannot
+//     name an arbitrary skill or shell command. The instruction is passed as
+//     data, never interpolated into a shell line.
+//   • The spawned CLI still runs under bypassPermissions bounded by the
+//     load-bearing deny list in .claude/settings.json (no rm/sudo/secret reads/
+//     network-from-shell/etc.).
+//
+// These are FIRST-PARTY skills (gstack, shipped with the repo), NOT
+// agent-authored code — so this does not violate the "never load/execute
+// LLM-authored code" invariant. The agent only chooses WHICH allowlisted skill
+// and WHAT instruction; it never supplies the skill body.
+
+import { runClaudeCodeAgent } from '../../agent-engines.js';
+import { DATA_DIR, WORKSPACE } from '../../paths.js';
+import { redactToolOutput } from '../safety.js';
+
+const DEFAULT_TIMEOUT_MS = 180000;
+const MAX_TIMEOUT_MS = 600000;
+const MAX_INSTRUCTION_CHARS = 4000;
+const MAX_SUMMARY_CHARS = 12000;
+const DEFAULT_MAX_TURNS = 25;
+
+// Allowlisted skills the bridge may invoke, keyed by the slug the agent passes.
+// Each entry: how to phrase the invocation + a one-line purpose. Keep this list
+// SHORT and visible-browser-focused; adding an entry widens the trust surface.
+const SKILL_BRIDGE_ALLOWLIST = {
+  'connect-chrome': {
+    purpose: 'Launch the visible GStack Chromium browser the operator can watch live.',
+    invoke: 'connect-chrome',
+  },
+  browse: {
+    purpose: 'Drive a browser to navigate, click, type, read pages, and capture screenshots.',
+    invoke: 'browse',
+  },
+  'qa-only': {
+    purpose: 'Run a QA pass against a running site and report findings (no fixes).',
+    invoke: 'qa-only',
+  },
+};
+
+export function listBridgeableSkills() {
+  return Object.entries(SKILL_BRIDGE_ALLOWLIST).map(([slug, meta]) => ({ slug, purpose: meta.purpose }));
+}
+
+function maxSummaryChars() {
+  const v = Number(process.env.MADARX_TOOL_OUTPUT_MAX_BYTES || MAX_SUMMARY_CHARS);
+  if (!Number.isFinite(v) || v <= 0) return MAX_SUMMARY_CHARS;
+  return Math.min(MAX_SUMMARY_CHARS, Math.floor(v));
+}
+
+function capSummary(text) {
+  return redactToolOutput(String(text || '').slice(0, maxSummaryChars()));
+}
+
+// Sync validation — runs BEFORE the approval/trust gates (PREFLIGHTS map). Throw
+// to reject outright; never reach the model with an off-allowlist skill.
+export function skillBridgeRunPreflight(input = {}) {
+  if (process.env.MADARX_SKILL_BRIDGE_DISABLED === '1') {
+    throw new Error('skill bridge is disabled (MADARX_SKILL_BRIDGE_DISABLED=1)');
+  }
+  const skill = String(input.skill || '').trim().toLowerCase();
+  if (!skill) throw new Error('skill is required');
+  const entry = SKILL_BRIDGE_ALLOWLIST[skill];
+  if (!entry) {
+    throw new Error(`skill "${skill}" is not bridgeable. Allowed: ${Object.keys(SKILL_BRIDGE_ALLOWLIST).join(', ')}`);
+  }
+  const instruction = String(input.instruction || '').trim();
+  if (!instruction) throw new Error('instruction is required');
+  if (instruction.length > MAX_INSTRUCTION_CHARS) {
+    throw new Error(`instruction is too long: ${instruction.length} chars; max ${MAX_INSTRUCTION_CHARS}`);
+  }
+  const timeoutMs = Math.max(
+    5000,
+    Math.min(MAX_TIMEOUT_MS, Number(input.timeout_ms || DEFAULT_TIMEOUT_MS) || DEFAULT_TIMEOUT_MS),
+  );
+  return { skill, entry, instruction, timeoutMs };
+}
+
+function buildSystemPrompt(skill, entry) {
+  return [
+    'You are a single-purpose runner spawned by the madarX main agent.',
+    `Your ONLY job: invoke the /${entry.invoke} skill and carry out the operator instruction with it.`,
+    `Purpose of this skill: ${entry.purpose}`,
+    'Rules:',
+    `- Use ONLY the /${entry.invoke} skill. Do not invoke other skills, write files outside workspace, or run unrelated commands.`,
+    '- Do not read secrets, .env files, or anything the deny list blocks.',
+    '- When done, reply with a concise plain-text summary of what happened and what you observed (URLs visited, key results). No markdown tables.',
+  ].join('\n');
+}
+
+export async function skillBridgeRun(input = {}, options = {}) {
+  const { skill, entry, instruction, timeoutMs } = skillBridgeRunPreflight(input);
+  const started = Date.now();
+
+  const systemPrompt = buildSystemPrompt(skill, entry);
+  const userMessage = `Use the /${entry.invoke} skill to do the following:\n\n${instruction}`;
+
+  try {
+    const text = await runClaudeCodeAgent({
+      systemPrompt,
+      userMessage,
+      maxTurns: DEFAULT_MAX_TURNS,
+      timeoutMs,
+      // Bounded toolset the gstack skills need (browser daemon runs via Bash).
+      // bypassPermissions + the .claude deny list remain the hard boundary.
+      allowedTools: ['Skill', 'Bash', 'Read', 'Write', 'Glob', 'Grep', 'WebFetch', 'WebSearch'],
+      addDirs: [WORKSPACE, DATA_DIR],
+      agentId: options.agent_id || 'main',
+      agentName: 'skill-bridge',
+    });
+
+    const summary = capSummary(text);
+    return {
+      ok: true,
+      tool: 'skill_bridge_run',
+      status: 'complete',
+      skill,
+      summary,
+      duration_ms: Date.now() - started,
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      tool: 'skill_bridge_run',
+      status: 'failed',
+      skill,
+      error: String(err?.message || err).slice(0, 1000),
+      duration_ms: Date.now() - started,
+    };
+  }
+}

package/lib/tools/registry.js

@@ -61,6 +61,7 @@ import { gmail_messages_list, gmail_message_read, gmail_thread_read } from './ad
 import { calendar_events_list, calendar_event_read } from './adapters/google-calendar.js';
 import { transcribe_audio } from './adapters/transcribe.js';
 import { browserHarnessRun, browserHarnessRunPreflight } from './adapters/browser-harness.js';
+import { skillBridgeRun, skillBridgeRunPreflight } from './adapters/skill-bridge.js';
 import { browserNavigate, browserExtractStructured } from './adapters/browser-fetch.js';
 import { browserOpen, browserAct, browserExtract, browserScreenshot } from './adapters/browser-session.js';
 import { voice_speak } from './adapters/tts.js';
@@ -348,6 +349,36 @@ const MARKETPLACE_TOOLS = [
       required: ['script'],
     },
   },
+  {
+    name: 'skill_bridge_run',
+    title: 'Skill Bridge',
+    description: 'Run one allowlisted first-party gstack CLI skill (connect-chrome, browse, qa-only) to drive the real visible browser the operator can watch live. Crosses the Claude Code CLI trust boundary, so it is ALWAYS approval-gated for every run (even in trust-mode auto) and disabled by default. Pass the skill slug and a plain-language instruction; the bridge invokes only that skill, bounded by the .claude deny list.',
+    category: 'browser',
+    risk_level: 'irreversible_external',
+    approval_required: true,
+    approval_mode: 'approval_required',
+    required_env: [],
+    enabled_default: false,
+    allowlist_required: false,
+    rate_limit: { window_seconds: 300, max: 10 },
+    input_schema: {
+      type: 'object',
+      properties: {
+        skill: {
+          type: 'string',
+          description: 'Skill slug to invoke. One of: connect-chrome, browse, qa-only.',
+          enum: ['connect-chrome', 'browse', 'qa-only'],
+        },
+        instruction: {
+          type: 'string',
+          description: 'Plain-language instruction for the skill (e.g. "open Google News and search US Iran war, read the top 3 headlines"). Max 4000 chars.',
+        },
+        timeout_ms: { type: 'number', description: 'Timeout in milliseconds, capped at 600000. Default 180000.' },
+        approval_id: { type: 'string', description: 'Approval request ID for one-shot execution.' },
+      },
+      required: ['skill', 'instruction'],
+    },
+  },
   {
     name: 'browser_open',
     title: 'Browser Open (Playwright)',
@@ -773,7 +804,7 @@ const MARKETPLACE_TOOLS = [
   {
     name: 'gh_repo_list',
     title: 'List GitHub repos',
-    description: 'List GitHub repositories accessible to the configured token.',
+    description: 'List GitHub repositories the token can access. Without `org`, lists across all affiliations (owned + collaborator + organization_member). Pass `org` to list a specific organization\'s repos you were granted access to.',
     category: 'github',
     risk_level: 'low',
     required_env: ['GITHUB_TOKEN'],
@@ -784,10 +815,13 @@ const MARKETPLACE_TOOLS = [
     input_schema: {
       type: 'object',
       properties: {
-        visibility: { type: 'string', description: 'Filter by visibility: all, public, private.' },
-        type: { type: 'string', description: 'Filter by type: all, owner, member.' },
+        org: { type: 'string', description: 'List repos for this organization/owner (GET /orgs/{org}/repos). Use this to reach org repos you were granted access to.' },
+        affiliation: { type: 'string', description: 'Comma-separated: owner, collaborator, organization_member. Default lists all three. Ignored when `org` is set.' },
+        visibility: { type: 'string', description: 'Filter by visibility: all, public, private. Ignored when `org` is set.' },
+        type: { type: 'string', description: 'Without org: all|owner|member (mutually exclusive with affiliation). With org: all|public|private|forks|sources|member.' },
         sort: { type: 'string', description: 'Sort by: created, updated, pushed, full_name.' },
         per_page: { type: 'number', description: 'Results per page, 1-100. Default 30.' },
+        page: { type: 'number', description: 'Page number for pagination. Default 1.' },
       },
     },
   },
@@ -1737,6 +1771,7 @@ const ADAPTERS = {
   calendar_event_read,
   transcribe_audio,
   browser_harness_run: browserHarnessRun,
+  skill_bridge_run: skillBridgeRun,
   browser_open: browserOpen,
   browser_act: browserAct,
   browser_extract: browserExtract,
@@ -1786,6 +1821,7 @@ const PREFLIGHTS = {
   process_start: processStartPreflight,
   process_kill: processKillPreflight,
   browser_harness_run: browserHarnessRunPreflight,
+  skill_bridge_run: skillBridgeRunPreflight,
 };
 
 function requiredEnvNames(required = []) {
@@ -2461,7 +2497,7 @@ export async function executeRegistryTool(toolName, input = {}, options = {}) {
   // existing contract — the owner's explicit per-agent permission mode governs
   // them — except browser_harness_run, which has always force-gated here.
   const agentIrreversibleGate = isIrreversibleExternal(tool, input)
-    && (toolName === 'browser_harness_run' || Boolean(tool.source));
+    && (toolName === 'browser_harness_run' || toolName === 'skill_bridge_run' || Boolean(tool.source));
   if (options.agent_id && agentIrreversibleGate && !consumeApprovalRequest(input.approval_id, { action_type: `agent_tool_irreversible:${toolName}` })) {
     const req = createApprovalRequest({
       action_type: `agent_tool_irreversible:${toolName}`,

package/lib/voice/context.js

@@ -210,7 +210,7 @@ export function buildVoiceContext(opts = {}) {
     'Cross-scope access: find_artifacts searches every project, not just the active one. Call list_projects to enumerate projects on demand. Call get_state with project_id="<slug or id>" to read a specific project, or with project_id=null to read across all projects. Spaces are client-side UI tabs that group artifacts — they do not gate your reach; any artifact in any space is reachable via find_artifacts.',
   );
   sections.push(
-    'Rules: never speak API keys, ephemeral tokens, or secret values aloud. If a tool returns approval_required, tell the operator one short sentence and stop. Prefer artifact creation for anything longer than ~30 spoken seconds. Never invent artifact IDs — call find_artifacts or get_state first. To read an artifact\'s body, call read_artifact with the id from find_artifacts; do NOT claim you have read it until that call returns content. ARTIFACT CREATION — choose the right tool: (1) For any VISUAL result the operator expects to look designed — a list page, snapshot, brief, report, dashboard, presentation, landing page, "make a page for X", "show me X" — call generate_ui with a specific description that includes the actual content/data to render. generate_ui produces a full styled HTML document using the madarX brand system (typography, color, layout). (2) For plain written notes, scratch summaries, or pure markdown exports the operator asked for explicitly, use create_artifact with kind="markdown". Never use create_artifact for visual outputs — it stores raw text and the dashboard renders it as a basic document, not a designed page. Whenever the operator asks for a summary, brief, page, doc, or report, create the artifact unprompted as the result of the turn — do not ask for permission first.',
+    'Rules: never speak API keys, ephemeral tokens, or secret values aloud. If a tool returns approval_required, tell the operator one short sentence and stop. Prefer artifact creation for anything longer than ~30 spoken seconds. Never invent artifact IDs — call find_artifacts or get_state first. To read an artifact\'s body, call read_artifact with the id from find_artifacts; do NOT claim you have read it until that call returns content. ARTIFACT CREATION — choose the right tool: (1) For any VISUAL result the operator expects to look designed — a list page, snapshot, brief, report, dashboard, presentation, landing page, "make a page for X", "show me X" — call generate_ui with a specific description that includes the actual content/data to render. generate_ui produces a full styled HTML document using the madarX brand system (typography, color, layout). (2) For plain written notes, scratch summaries, or pure markdown exports the operator asked for explicitly, use create_artifact with kind="markdown". Never use create_artifact for visual outputs — it stores raw text and the dashboard renders it as a basic document, not a designed page. Whenever the operator asks for a summary, brief, page, doc, or report, create the artifact unprompted as the result of the turn — do not ask for permission first. BRAND IS MANDATORY: every visual artifact MUST follow the madarX brand guidelines above (palette, typography, layout) — generate_ui applies them automatically, so always route designed output through generate_ui. Never emit an off-brand layout, default-looking page, or any emoji in an artifact.',
   );
 
   const instructions = sections.join('\n\n').slice(0, 7800);

package/lib/voice/tools.js

@@ -64,8 +64,40 @@ function mainAgentToolList() {
   return getTools();
 }
 
+// Voice gets the SAME full tool catalog as the typed main agent — that is the
+// product contract (voice IS the main agent) and it must match what the voice
+// instruction block advertises (lib/voice/context.js lists every tool by name).
+// Latency is controlled the right way instead: session.reasoning.effort='low'
+// on gpt-realtime-2 (lib/realtime-openai.js) keeps first-audio snappy while the
+// model still has the whole toolset. The model's improved tool-selection avoids
+// over-calling on chit-chat. For deployments that prefer a tiny conversational
+// toolset over capability, set MADARX_VOICE_FAST_TOOLS=1 to trim to this set.
+const FAST_VOICE_TOOL_NAMES = new Set([
+  'web_search',
+  'web_fetch',
+  'find_artifacts',
+  'get_state',
+  'create_artifact',
+  'update_artifact',
+  'generate_ui',
+  'voice_speak',
+  'create_agent',
+  'upsert_schedule',
+]);
+
+function voiceToolList() {
+  const all = mainAgentToolList();
+  if (process.env.MADARX_VOICE_FAST_TOOLS === '1') {
+    const trimmed = all.filter(t => FAST_VOICE_TOOL_NAMES.has(t.name));
+    if (trimmed.length) return trimmed;
+  }
+  return all;
+}
+
 export function getVoiceToolCatalog() {
-  return mainAgentToolList().map(tool => ({
+  // Same source as getVoiceToolsForRealtime so the advertised tool list in the
+  // instruction block always matches what is actually attached to the session.
+  return voiceToolList().map(tool => ({
     name: tool.name,
     title: humanTitle(tool.name),
     description: tool.description || '',
@@ -74,7 +106,7 @@ export function getVoiceToolCatalog() {
 }
 
 export function getVoiceToolsForRealtime() {
-  return mainAgentToolList().map(toRealtimeShape);
+  return voiceToolList().map(toRealtimeShape);
 }
 
 export function isVoiceTool(name) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "madarx",
-  "version": "2.17.0",
+  "version": "2.18.0",
   "type": "module",
   "description": "Madarx OS — Next.js product with SQLite-backed runtime, scheduled cron daemon, and approval-gated local runners.",
   "license": "MIT",

package/scripts/migrate-auth-v1.mjs

@@ -83,6 +83,15 @@ export function runAuthV1Migration(db) {
      VALUES ('mem-local-owner', 'personal-org', 'local-user-1', 'owner', ?)`
   ).run(now);
 
+  // ── Step 4b: Self-heal default-org ownership ──────────────────────────────
+  // The synthetic `local-user-1` owns personal-org (step 4). When the operator
+  // flips to Supabase mode and signs in, they get a `member` row — and because a
+  // membership now exists, the first-login owner-bootstrap is skipped, so they
+  // are permanently stuck below admin (every owner/admin gate 403s). Promote the
+  // real operator to owner of their own default org. Idempotent + conservative:
+  // only acts when there is NO real owner yet and the operator is unambiguous.
+  const heal = healDefaultOrgOwnership(db);
+
   // ── Step 5: Bind orphaned projects to personal-org ────────────────────────
   const projectsResult = db
     .prepare("UPDATE projects SET org_id = 'personal-org' WHERE org_id IS NULL")
@@ -97,9 +106,91 @@ export function runAuthV1Migration(db) {
   return {
     projectsUpdated: projectsResult.changes,
     artifactsUpdated: artifactsResult.changes,
+    ownershipHeal: heal,
   };
 }
 
+const SYNTHETIC_LOCAL_USER = 'local-user-1';
+const DEFAULT_ORG = 'personal-org';
+
+/**
+ * Ensure the real operator owns the default org (`personal-org`).
+ *
+ * Why: the seed makes the synthetic `local-user-1` the owner. In Supabase mode a
+ * real user is added as a `member`, and the owner-bootstrap is then skipped (a
+ * membership already exists), leaving the operator permanently below admin.
+ *
+ * Rule (idempotent, conservative — never downgrades, never guesses):
+ *   • If a real (non-synthetic) owner already exists → no-op.
+ *   • Else, among real members of the default org:
+ *       - exactly one  → promote them to owner (they are the operator).
+ *       - two or more  → ambiguous; promote only the one matching
+ *                        MADARX_OWNER_EMAIL if set, else leave for a human.
+ *       - zero         → no-op (pure local install, no real user yet).
+ *
+ * @param {DatabaseSync} db
+ * @returns {{ status: string, user_id?: string, basis?: string, count?: number }}
+ */
+export function healDefaultOrgOwnership(db) {
+  const org = db.prepare('SELECT id FROM organizations WHERE id = ?').get(DEFAULT_ORG);
+  if (!org) return { status: 'no_default_org' };
+
+  const realOwner = db
+    .prepare("SELECT user_id FROM org_memberships WHERE org_id = ? AND role = 'owner' AND user_id != ?")
+    .get(DEFAULT_ORG, SYNTHETIC_LOCAL_USER);
+  if (realOwner) return { status: 'already_owned', user_id: realOwner.user_id };
+
+  const realMembers = db
+    .prepare("SELECT user_id FROM org_memberships WHERE org_id = ? AND user_id != ?")
+    .all(DEFAULT_ORG, SYNTHETIC_LOCAL_USER);
+  if (realMembers.length === 0) return { status: 'no_real_user' };
+
+  let targetUserId;
+  let basis;
+  if (realMembers.length === 1) {
+    targetUserId = realMembers[0].user_id;
+    basis = 'sole_member';
+  } else {
+    // Ambiguous default org — only act on an explicit operator-of-record.
+    const ownerEmail = process.env.MADARX_OWNER_EMAIL;
+    if (!ownerEmail || ownerEmail === 'owner@local.dev') return { status: 'ambiguous', count: realMembers.length };
+    const match = db
+      .prepare(
+        `SELECT m.user_id FROM org_memberships m JOIN users u ON u.id = m.user_id
+         WHERE m.org_id = ? AND m.user_id != ? AND lower(u.email) = lower(?)`
+      )
+      .all(DEFAULT_ORG, SYNTHETIC_LOCAL_USER, ownerEmail);
+    if (match.length !== 1) return { status: 'ambiguous', count: realMembers.length };
+    targetUserId = match[0].user_id;
+    basis = 'owner_email';
+  }
+
+  const res = db
+    .prepare("UPDATE org_memberships SET role = 'owner' WHERE org_id = ? AND user_id = ? AND role != 'owner'")
+    .run(DEFAULT_ORG, targetUserId);
+  if (!res.changes) return { status: 'already_owned', user_id: targetUserId };
+
+  // Best-effort audit — never block boot on it.
+  try {
+    db.prepare(
+      `INSERT INTO audit_logs (id, at, type, summary, status, meta, user_id, org_id, action_target_id, action_target_type)
+       VALUES (?, ?, 'auth.default_org.owner_healed', ?, 'success', ?, ?, ?, ?, 'org_membership')`
+    ).run(
+      `audit-orgheal-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+      nowIso(),
+      `Promoted real operator to owner of ${DEFAULT_ORG} (was member; default org was owned only by synthetic ${SYNTHETIC_LOCAL_USER})`,
+      JSON.stringify({ org_id: DEFAULT_ORG, user_id: targetUserId, basis }),
+      targetUserId,
+      DEFAULT_ORG,
+      targetUserId,
+    );
+  } catch {
+    // audit table not ready / schema drift — promotion still stands.
+  }
+
+  return { status: 'promoted', user_id: targetUserId, basis };
+}
+
 // ── CLI entry point ───────────────────────────────────────────────────────────
 // ESM direct-run guard: only execute main() when this file is the entry point,
 // not when imported as a module (e.g. by lib/seeds.js).
@@ -133,6 +224,7 @@ async function main() {
     console.log('  personal-org: ensured');
     console.log('  local-user-1: ensured (email: ' + ownerEmail + ')');
     console.log('  owner membership: ensured');
+    console.log('  ownership heal: ' + result.ownershipHeal.status + (result.ownershipHeal.user_id ? ' (' + result.ownershipHeal.user_id + ')' : ''));
     console.log('  projects bound: ' + result.projectsUpdated);
     console.log('  artifacts defaulted: ' + result.artifactsUpdated);
     console.log('  marker: ' + MARKER);