@geraldmaron/construct 1.0.0 → 1.0.1

package/lib/handoffs/cleanup.mjs

@@ -0,0 +1,159 @@
+/**
+ * lib/handoffs/cleanup.mjs — automatic handoff hygiene.
+ *
+ * Lifecycle:
+ *   1. Open handoffs (referenced beads not all closed) stay where they are.
+ *   2. Resolved handoffs (referenced beads all closed) older than
+ *      `handoffsMaxDays` get MOVED to `.cx/handoffs/archive/`.
+ *   3. Archived handoffs older than `2 * handoffsMaxDays` get DELETED.
+ *   4. Any open handoff past `handoffsMaxItems` (FIFO by mtime) is
+ *      surfaced as a warning but never deleted — open work is sacred.
+ *
+ * The function is idempotent and runs from:
+ *   - `construct down` (best effort, time-boxed)
+ *   - doctor daemon tick (lib/doctor/watchers/handoffs.mjs)
+ *   - `construct handoffs prune` (manual)
+ *
+ * Planning never recurses into archive/. The archive deletion threshold
+ * compares against archive-dir mtimes, reset on move.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { loadProjectConfig } from '../config/project-config.mjs';
+import { parseHandoffFile } from './contract.mjs';
+
+const HANDOFFS_DIR = '.cx/handoffs';
+const ARCHIVE_DIR = '.cx/handoffs/archive';
+
+function bdRootCwd(projectRoot) {
+  try {
+    const r = spawnSync('git', ['rev-parse', '--git-common-dir'], { cwd: projectRoot, encoding: 'utf8' });
+    if (r.status !== 0) return projectRoot;
+    const trimmed = r.stdout.trim();
+    const resolved = trimmed.startsWith('/') ? trimmed : path.join(projectRoot, trimmed);
+    const candidate = path.dirname(resolved);
+    if (fs.existsSync(path.join(candidate, '.beads'))) return candidate;
+  } catch { /* fall through */ }
+  return projectRoot;
+}
+
+function loadClosedBeadIds(projectRoot) {
+  try {
+    const r = spawnSync('bd', ['list', '--status', 'closed', '--json'], {
+      cwd: bdRootCwd(projectRoot),
+      encoding: 'utf8',
+      env: { ...process.env, NO_COLOR: '1' },
+      timeout: 5000,
+    });
+    if (r.status !== 0) return new Set();
+    const issues = JSON.parse(r.stdout || '[]');
+    return new Set(issues.map((it) => String(it.id).toLowerCase()));
+  } catch { return new Set(); }
+}
+
+function listHandoffFiles(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter((f) => f.endsWith('.md'))
+    .map((f) => {
+      const full = path.join(dir, f);
+      const stat = fs.statSync(full);
+      return { filename: f, path: full, mtimeMs: stat.mtimeMs, bytes: stat.size };
+    });
+}
+
+function getRefBeads(filePath) {
+  try {
+    const parsed = parseHandoffFile(filePath);
+    if (Array.isArray(parsed.frontmatter?.beads) && parsed.frontmatter.beads.length > 0) {
+      return parsed.frontmatter.beads.map((s) => String(s).toLowerCase());
+    }
+    // Legacy fallback: scrape `construct-xxx` references from the body.
+    const text = parsed.body || '';
+    const matches = text.match(/\bconstruct-[a-z0-9]+\b/gi) || [];
+    return Array.from(new Set(matches.map((s) => s.toLowerCase())));
+  } catch {
+    return [];
+  }
+}
+
+export function planHandoffCleanup(projectRoot = process.cwd(), env = process.env, { now = Date.now() } = {}) {
+  const { config } = loadProjectConfig(projectRoot, env);
+  const disk = config?.resources?.disk || {};
+  const maxDays = disk.handoffsMaxDays ?? 30;
+  const maxItems = disk.handoffsMaxItems ?? 50;
+
+  const liveDir = path.join(projectRoot, HANDOFFS_DIR);
+  const archiveDir = path.join(projectRoot, ARCHIVE_DIR);
+  const liveFiles = listHandoffFiles(liveDir);
+  const archiveFiles = listHandoffFiles(archiveDir);
+
+  const archiveCutoff = now - maxDays * 24 * 60 * 60 * 1000;
+  const deleteCutoff = now - 2 * maxDays * 24 * 60 * 60 * 1000;
+
+  const closed = loadClosedBeadIds(projectRoot);
+  const actions = [];
+  const warnings = [];
+
+  for (const f of liveFiles) {
+    const beads = getRefBeads(f.path);
+    const allClosed = beads.length > 0 && beads.every((id) => closed.has(id));
+    if (allClosed && f.mtimeMs < archiveCutoff) {
+      actions.push({
+        kind: 'archive',
+        from: f.path,
+        to: path.join(archiveDir, f.filename),
+        reason: `referenced beads (${beads.join(', ')}) are closed and file is older than ${maxDays}d`,
+        bytes: f.bytes,
+      });
+    }
+  }
+
+  for (const f of archiveFiles) {
+    if (f.mtimeMs < deleteCutoff) {
+      actions.push({
+        kind: 'delete',
+        path: f.path,
+        reason: `archived handoff older than ${2 * maxDays}d`,
+        bytes: f.bytes,
+      });
+    }
+  }
+
+  // Soft warning when too many live handoffs accumulate. Never delete
+  // live handoffs automatically — they may reference open work.
+  if (liveFiles.length > maxItems) {
+    warnings.push(`${liveFiles.length} live handoffs exceeds maxItems=${maxItems}. Close or archive resolved beads to bring it down.`);
+  }
+
+  return { actions, warnings, maxDays, maxItems, archiveCutoff, deleteCutoff };
+}
+
+export function executeHandoffCleanup(plan) {
+  const moved = [];
+  const deleted = [];
+  for (const a of plan.actions) {
+    try {
+      if (a.kind === 'archive') {
+        fs.mkdirSync(path.dirname(a.to), { recursive: true });
+        fs.renameSync(a.from, a.to);
+        moved.push(a);
+      } else if (a.kind === 'delete') {
+        fs.unlinkSync(a.path);
+        deleted.push(a);
+      }
+    } catch (err) {
+      a.error = err.message;
+    }
+  }
+  return { moved, deleted, warnings: plan.warnings };
+}
+
+export function autoCleanHandoffs(projectRoot = process.cwd(), env = process.env) {
+  const plan = planHandoffCleanup(projectRoot, env);
+  if (plan.actions.length === 0) return { plan, result: { moved: [], deleted: [], warnings: plan.warnings } };
+  const result = executeHandoffCleanup(plan);
+  return { plan, result };
+}

package/lib/handoffs/contract.mjs

@@ -0,0 +1,162 @@
+/**
+ * lib/handoffs/contract.mjs — handoff schema + parse/validate/format.
+ *
+ * A handoff is a markdown file in `.cx/handoffs/` written when a session
+ * bridges work to the next agent. Until now the shape was implicit, so
+ * handoffs varied in quality and there was no automated cleanup beyond
+ * raw mtime/count caps. This module defines a contract:
+ *
+ *   ---
+ *   schema: cx-handoff/v1
+ *   id: 2026-05-18-something-something            # filename stem
+ *   created: 2026-05-18T14:00:00.000Z
+ *   from_session: <session-uuid-or-alias>
+ *   beads: [construct-xyz, construct-abc]         # work this handoff is about
+ *   status: open                                   # open | resolved | archived
+ *   title: One-line summary
+ *   tags: [optional, free-form]
+ *   ---
+ *
+ *   ## What was done
+ *   …
+ *   ## What's left
+ *   …
+ *   ## Open questions
+ *   …
+ *   ## How to resume
+ *   …
+ *
+ * Status semantics:
+ *   - open      — bead(s) still in progress or open; handoff is live context
+ *   - resolved  — every referenced bead is closed; handoff is informational
+ *   - archived  — moved to .cx/handoffs/archive/ during cleanup
+ *
+ * Cleanup uses these fields:
+ *   - resolved handoffs older than retention → archived
+ *   - archived handoffs older than 2× retention → deleted
+ *   - any handoff past `handoffsMaxItems` (FIFO by mtime) → deleted
+ *
+ * `parseHandoff` is intentionally permissive — pre-contract handoffs with
+ * no frontmatter still parse with status='legacy' so they aren't lost.
+ * `validateHandoff` is the strict version, used when writing.
+ */
+
+import { readFileSync } from 'node:fs';
+
+export const HANDOFF_SCHEMA_VERSION = 'cx-handoff/v1';
+export const HANDOFF_STATUSES = Object.freeze(['open', 'resolved', 'archived']);
+export const REQUIRED_SECTIONS = Object.freeze(['What was done', "What's left"]);
+
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/;
+
+function parseFrontmatterBlock(text) {
+  const out = {};
+  for (const line of text.split('\n')) {
+    if (!line.trim() || line.trim().startsWith('#')) continue;
+    const idx = line.indexOf(':');
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    const rawValue = line.slice(idx + 1).trim();
+    if (!key) continue;
+    if (rawValue.startsWith('[') && rawValue.endsWith(']')) {
+      out[key] = rawValue.slice(1, -1).split(',').map((s) => s.trim()).filter(Boolean);
+    } else if (rawValue === 'true' || rawValue === 'false') {
+      out[key] = rawValue === 'true';
+    } else if (/^-?\d+(\.\d+)?$/.test(rawValue)) {
+      out[key] = Number(rawValue);
+    } else {
+      const unquoted = rawValue.replace(/^["']|["']$/g, '');
+      out[key] = unquoted;
+    }
+  }
+  return out;
+}
+
+export function parseHandoff(text) {
+  if (typeof text !== 'string') {
+    return { frontmatter: {}, body: '', sections: {}, status: 'invalid', error: 'text required' };
+  }
+  const fmMatch = text.match(FRONTMATTER_RE);
+  let frontmatter = {};
+  let body = text;
+  if (fmMatch) {
+    frontmatter = parseFrontmatterBlock(fmMatch[1]);
+    body = text.slice(fmMatch[0].length);
+  }
+  const sections = {};
+  let currentHeading = null;
+  let currentLines = [];
+  for (const line of body.split('\n')) {
+    const heading = line.match(/^##\s+(.+?)\s*$/);
+    if (heading) {
+      if (currentHeading) sections[currentHeading] = currentLines.join('\n').trim();
+      currentHeading = heading[1];
+      currentLines = [];
+    } else if (currentHeading) {
+      currentLines.push(line);
+    }
+  }
+  if (currentHeading) sections[currentHeading] = currentLines.join('\n').trim();
+
+  const status = frontmatter?.schema === HANDOFF_SCHEMA_VERSION
+    ? (HANDOFF_STATUSES.includes(frontmatter.status) ? frontmatter.status : 'open')
+    : 'legacy';
+  return { frontmatter, body, sections, status };
+}
+
+export function parseHandoffFile(filePath) {
+  const text = readFileSync(filePath, 'utf8');
+  return parseHandoff(text);
+}
+
+export function validateHandoff(parsed) {
+  const errors = [];
+  const fm = parsed?.frontmatter || {};
+  if (fm.schema !== HANDOFF_SCHEMA_VERSION) errors.push(`schema must be '${HANDOFF_SCHEMA_VERSION}'`);
+  if (typeof fm.id !== 'string' || !fm.id) errors.push('id required (typically the filename stem)');
+  if (typeof fm.created !== 'string' || !/\d{4}-\d{2}-\d{2}/.test(fm.created)) errors.push("created required (ISO-8601 string starting with YYYY-MM-DD)");
+  if (typeof fm.title !== 'string' || !fm.title.trim()) errors.push('title required');
+  if (fm.status && !HANDOFF_STATUSES.includes(fm.status)) errors.push(`status must be one of ${HANDOFF_STATUSES.join(', ')}`);
+  if (fm.beads !== undefined && !Array.isArray(fm.beads)) errors.push('beads must be an array of bd issue ids');
+  for (const section of REQUIRED_SECTIONS) {
+    if (!parsed?.sections?.[section] || !parsed.sections[section].trim()) {
+      errors.push(`required section missing or empty: "${section}"`);
+    }
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+export function formatHandoff({ id, title, beads = [], status = 'open', from_session = null, tags = [], whatWasDone = '', whatsLeft = '', openQuestions = '', howToResume = '' } = {}) {
+  if (!id) throw new Error('formatHandoff: id required');
+  if (!title) throw new Error('formatHandoff: title required');
+  const lines = [
+    '---',
+    `schema: ${HANDOFF_SCHEMA_VERSION}`,
+    `id: ${id}`,
+    `created: ${new Date().toISOString()}`,
+    from_session ? `from_session: ${from_session}` : null,
+    `beads: [${beads.join(', ')}]`,
+    `status: ${status}`,
+    `title: ${JSON.stringify(title)}`,
+    tags.length ? `tags: [${tags.join(', ')}]` : null,
+    '---',
+    '',
+    '## What was done',
+    '',
+    whatWasDone.trim() || '_TBD_',
+    '',
+    "## What's left",
+    '',
+    whatsLeft.trim() || '_TBD_',
+    '',
+    '## Open questions',
+    '',
+    openQuestions.trim() || '_(none)_',
+    '',
+    '## How to resume',
+    '',
+    howToResume.trim() || '_TBD_',
+    '',
+  ].filter((line) => line !== null);
+  return lines.join('\n');
+}

package/lib/handoffs/inventory.mjs

@@ -0,0 +1,120 @@
+/**
+ * lib/handoffs/inventory.mjs — handoff hygiene primitives.
+ *
+ * Handoffs (markdown files in `.cx/handoffs/`) are written by
+ * `lib/beads-automation.mjs::create-handoff` whenever a session bridges
+ * to the next agent. The inventory helper surfaces:
+ *
+ *   - total file count + total bytes
+ *   - oldest mtime (age, in days)
+ *   - count of files past `handoffsMaxDays` (eligible to prune)
+ *   - count of files referencing a *closed* bead (stale-but-resolved)
+ *   - per-file id, status, and path (from contract parser) for CLI display
+ *
+ * The dashboard insights card consumes this; doctor surfaces a warning
+ * when stale handoffs accumulate past the threshold.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { loadProjectConfig } from '../config/project-config.mjs';
+import { parseHandoff } from './contract.mjs';
+
+const HANDOFFS_REL = '.cx/handoffs';
+const BEAD_REF_RE = /\bconstruct-[a-z0-9]+\b/gi;
+
+function readFiles(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter((f) => f.endsWith('.md'))
+    .map((f) => {
+      const full = path.join(dir, f);
+      const stat = fs.statSync(full);
+      const content = fs.readFileSync(full, 'utf8');
+      const beadRefs = Array.from(new Set((content.match(BEAD_REF_RE) || []).map((s) => s.toLowerCase())));
+      const parsed = parseHandoff(content);
+      const id = parsed.frontmatter?.id || f.replace(/\.md$/, '');
+      return { filename: f, id, path: full, mtimeMs: stat.mtimeMs, bytes: stat.size, beadRefs, status: parsed.status };
+    });
+}
+
+function bdRootCwd(projectRoot) {
+  try {
+    const r = spawnSync('git', ['rev-parse', '--git-common-dir'], { cwd: projectRoot, encoding: 'utf8' });
+    if (r.status !== 0) return projectRoot;
+    const trimmed = r.stdout.trim();
+    const resolved = trimmed.startsWith('/') ? trimmed : path.join(projectRoot, trimmed);
+    const candidate = path.dirname(resolved);
+    if (fs.existsSync(path.join(candidate, '.beads'))) return candidate;
+  } catch { /* fall through */ }
+  return projectRoot;
+}
+
+function closedBeadIds(projectRoot) {
+  try {
+    const r = spawnSync('bd', ['list', '--status', 'closed', '--json'], {
+      cwd: bdRootCwd(projectRoot),
+      encoding: 'utf8',
+      env: { ...process.env, NO_COLOR: '1' },
+      timeout: 5000,
+    });
+    if (r.status !== 0) return new Set();
+    const issues = JSON.parse(r.stdout);
+    return new Set(issues.map((it) => String(it.id).toLowerCase()));
+  } catch { return new Set(); }
+}
+
+export function summarizeHandoffs(projectRoot = process.cwd(), env = process.env, { now = Date.now() } = {}) {
+  const dir = path.join(projectRoot, HANDOFFS_REL);
+  const files = readFiles(dir);
+  if (files.length === 0) {
+    return {
+      state: 'empty',
+      total: 0,
+      bytes: 0,
+      oldestAgeDays: null,
+      pastRetentionCount: 0,
+      resolvedCount: 0,
+    };
+  }
+  const { config } = loadProjectConfig(projectRoot, env);
+  const maxDays = config?.resources?.disk?.handoffsMaxDays ?? 30;
+  const maxItems = config?.resources?.disk?.handoffsMaxItems ?? 50;
+  const cutoff = now - maxDays * 24 * 60 * 60 * 1000;
+  const sorted = [...files].sort((a, b) => a.mtimeMs - b.mtimeMs);
+  const oldestAgeMs = now - sorted[0].mtimeMs;
+  const closed = closedBeadIds(projectRoot);
+  let pastRetentionCount = 0;
+  let resolvedCount = 0;
+  let resolvedFiles = [];
+  for (const f of files) {
+    if (f.mtimeMs < cutoff) pastRetentionCount += 1;
+    if (f.beadRefs.length > 0 && f.beadRefs.every((id) => closed.has(id))) {
+      resolvedCount += 1;
+      resolvedFiles.push(f.filename);
+    }
+  }
+  const bytes = files.reduce((s, f) => s + f.bytes, 0);
+  const enriched = files.map((f) => ({
+    ...f,
+    ageDays: (now - f.mtimeMs) / (24 * 60 * 60 * 1000),
+  }));
+  return {
+    state: 'ok',
+    total: files.length,
+    bytes,
+    oldestAgeDays: oldestAgeMs / (24 * 60 * 60 * 1000),
+    maxDays,
+    maxItems,
+    pastRetentionCount,
+    resolvedCount,
+    resolvedFiles: resolvedFiles.slice(0, 10),
+    files: enriched,
+    recent: sorted.slice(-5).reverse().map((f) => ({
+      filename: f.filename,
+      ageDays: (now - f.mtimeMs) / (24 * 60 * 60 * 1000),
+      beadRefs: f.beadRefs,
+      bytes: f.bytes,
+    })),
+  };
+}

package/lib/headhunt.mjs

@@ -1,16 +1,18 @@
 #!/usr/bin/env node
 /**
- * lib/headhunt.mjs — <one-line purpose>
+ * lib/headhunt.mjs — Domain overlay activation and promotion for Construct agents.
  *
- * <2–6 line summary.>
+ * Creates temporary domain overlays that attach specialist knowledge to named
+ * agents, tracks overlay expiry, and manages promotion requests when a transient
+ * overlay should become a permanent skill. Backs the `construct headhunt` CLI
+ * and the MCP headhunt tool.
  */
 
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { createInterface } from 'node:readline';
-
-import { loadWorkflow, updateTask } from './workflow-state.mjs';
+import { selectOption } from './tty-prompts.mjs';
 
 const OVERLAY_DIRNAME = 'domain-overlays';
 const PROMOTION_DIRNAME = 'promotion-requests';
@@ -181,45 +183,12 @@ function unique(values = []) {
   return [...new Set((values || []).filter(Boolean))];
 }
 
-function findWorkflowTaskForOverlay(workflow, overlayId = null) {
-  const tasks = workflow?.tasks || [];
-  if (overlayId) {
-    const linkedTask = tasks.find((task) => Array.isArray(task.overlays) && task.overlays.includes(overlayId));
-    if (linkedTask) return linkedTask;
-  }
-  if (workflow?.currentTaskKey) {
-    const currentTask = tasks.find((task) => task.key === workflow.currentTaskKey);
-    if (currentTask) return currentTask;
-  }
-  return tasks.find((task) => task.status === 'in-progress' || task.status === 'blocked_needs_user') || null;
-}
-
 function attachOverlayToWorkflow(root, overlay, { challengeRequired = false, challengeStatus = null } = {}) {
-  const workflow = loadWorkflow(root);
-  const task = findWorkflowTaskForOverlay(workflow);
-  if (!task) return null;
-
-  updateTask(root, task.key, {
-    overlays: unique([...(task.overlays || []), overlay.id]),
-    challengeRequired: challengeRequired || task.challengeRequired,
-    challengeStatus: challengeStatus ?? task.challengeStatus,
-    note: `Attached domain overlay ${overlay.id} (${overlay.domain}).`,
-  });
-  return task.key;
+  return null;
 }
 
 function syncPromotionToWorkflow(root, request) {
-  const workflow = loadWorkflow(root);
-  const task = findWorkflowTaskForOverlay(workflow, request.id);
-  if (!task) return null;
-
-  updateTask(root, task.key, {
-    overlays: unique([...(task.overlays || []), request.id]),
-    challengeRequired: true,
-    challengeStatus: request.challenge?.status || task.challengeStatus || 'pending',
-    note: `Updated promotion request ${request.id} challenge status to ${request.challenge?.status || 'pending'}.`,
-  });
-  return task.key;
+  return null;
 }
 
 function isExpired(record) {
@@ -384,7 +353,6 @@ export async function runHeadhunt({ args = [], cwd = process.cwd(), homeDir = os
     const overlayId = `${slugify(templateName)}-team-${now.toISOString().replace(/[:.]/g, '-')}`;
     const overlayDir = getOverlayDir(root);
     const expiresAt = permanence === 'temporary' ? new Date(now.getTime() + 7 * 24 * 60 * 60 * 1000).toISOString() : null;
-    const workflow = loadWorkflow(root);
 
     const overlay = {
       id: overlayId,
@@ -401,8 +369,8 @@ export async function runHeadhunt({ args = [], cwd = process.cwd(), homeDir = os
       createdAt: now.toISOString(),
       expiresAt,
       project: path.basename(root),
-      workflowId: workflow?.id || null,
-      taskKey: workflow?.currentTaskKey || null,
+      workflowId: null,
+      taskKey: null,
       status: 'active',
       prompt: buildOverlayPrompt({ domain: templateName, objective, scope: typeof flags.scope === 'string' ? flags.scope : '', permanence, focus: tpl.focus, freshness }),
       skills: tpl.skills ?? [],
@@ -450,8 +418,22 @@ export async function runHeadhunt({ args = [], cwd = process.cwd(), homeDir = os
   try {
     let permanence = flags.save ? 'permanent_request' : 'temporary';
     if (!flags.temp && !flags.save && interactive) {
-      const answer = (await promptQuestion(rl, 'Use this expertise temporarily for the current task, or save it as a promotion request? [temp/save]: ')).trim().toLowerCase();
-      permanence = answer === 'save' ? 'permanent_request' : 'temporary';
+      permanence = await selectOption({
+        title: 'Choose overlay mode',
+        instructions: 'Pick whether this expertise should be temporary or saved as a promotion request.',
+        options: [
+          {
+            value: 'temporary',
+            label: 'Temporary overlay',
+            description: 'Use this expertise for the current task and let it expire automatically.',
+          },
+          {
+            value: 'permanent_request',
+            label: 'Promotion request',
+            description: 'Save a request to promote this expertise into a more permanent capability.',
+          },
+        ],
+      });
     }
 
     let objective = typeof flags.for === 'string' ? flags.for.trim() : rest.slice(1).join(' ').trim();
@@ -469,7 +451,6 @@ export async function runHeadhunt({ args = [], cwd = process.cwd(), homeDir = os
     const classification = classifyOverlay(objective, typeof flags.team === 'string' ? flags.team : '');
     const now = new Date();
     const root = findConstructRoot(cwd);
-    const workflow = loadWorkflow(root);
     const overlayId = `${slugify(domain)}-${now.toISOString().replace(/[:.]/g, '-')}`;
     const overlayDir = getOverlayDir(root);
     const promotionDir = getPromotionDir(root);
@@ -488,8 +469,8 @@ export async function runHeadhunt({ args = [], cwd = process.cwd(), homeDir = os
       createdAt: now.toISOString(),
       expiresAt,
       project: path.basename(root),
-      workflowId: workflow?.id || null,
-      taskKey: workflow?.currentTaskKey || null,
+      workflowId: null,
+      taskKey: null,
       status: permanence === 'temporary' ? 'active' : 'promotion_requested',
       teamId: overlayId,
       sourceStrategy: [