indusagi-coding-agent 0.2.8 → 0.2.10

package/src/workflow-engine/engine.ts

@@ -0,0 +1,294 @@
+import vm from "node:vm";
+import os from "node:os";
+import { parseWorkflowScript, type WorkflowMeta } from "./parse.js";
+
+export interface WorkflowAgentActivity {
+  tokensIn: number;
+  tokensOut: number;
+  toolCount: number;
+  currentTool?: string;
+  lastTool?: string;
+}
+
+export interface WorkflowAgentRunOptions {
+  label: string;
+  phase?: string;
+  schema?: unknown;
+  instructions?: string;
+  model?: string;
+  agentType?: string;
+  isolation?: "worktree";
+  signal?: AbortSignal;
+  onActivity?: (metrics: WorkflowAgentActivity) => void;
+}
+
+export interface WorkflowAgentRunner {
+  run(prompt: string, options: WorkflowAgentRunOptions): Promise<unknown>;
+}
+
+export interface AgentOptions {
+  label?: string;
+  phase?: string;
+  schema?: unknown;
+  model?: string;
+  isolation?: "worktree";
+  agentType?: string;
+}
+
+export interface WorkflowRunOptions {
+  agentRunner: WorkflowAgentRunner;
+  args?: unknown;
+  cwd?: string;
+  concurrency?: number;
+  tokenBudget?: number | null;
+  signal?: AbortSignal;
+  onLog?: (message: string) => void;
+  onPhase?: (title: string) => void;
+  onAgentStart?: (event: { id: number; label: string; phase?: string; prompt: string }) => void;
+  onAgentEnd?: (event: { id: number; label: string; phase?: string; result: unknown }) => void;
+  onAgentActivity?: (id: number, metrics: WorkflowAgentActivity) => void;
+}
+
+export interface WorkflowRunResult<T = unknown> {
+  meta: WorkflowMeta;
+  result: T;
+  logs: string[];
+  phases: string[];
+  agentCount: number;
+  durationMs: number;
+}
+
+export const WORKFLOW_RUNTIME_BUDGET_MS = 1000;
+
+interface EngineState {
+  logs: string[];
+  phases: string[];
+  agentCount: number;
+  spent: number;
+  currentPhase?: string;
+}
+
+export async function runWorkflow<T = unknown>(script: string, options: WorkflowRunOptions): Promise<WorkflowRunResult<T>> {
+  const started = Date.now();
+  const { meta, body } = parseWorkflowScript(script);
+  const state: EngineState = { logs: [], phases: [], agentCount: 0, spent: 0 };
+  const { agentRunner } = options;
+  if (!agentRunner || typeof agentRunner.run !== "function") {
+    throw new TypeError("runWorkflow requires an agentRunner with a run() method");
+  }
+  const concurrency = Math.max(1, Math.min(options.concurrency ?? Math.max(1, defaultConcurrency() - 2), 16));
+  const limiter = createLimiter(concurrency);
+  const pendingAgentRuns = new Set<Promise<unknown>>();
+  const log = (message: unknown) => {
+    const text = String(message);
+    state.logs.push(text);
+    options.onLog?.(text);
+  };
+  const phase = (title: unknown) => {
+    const text = requireString(title, "phase title");
+    state.currentPhase = text;
+    if (!state.phases.includes(text)) state.phases.push(text);
+    options.onPhase?.(text);
+  };
+  const budget = Object.freeze({
+    total: options.tokenBudget ?? null,
+    spent: () => state.spent,
+    remaining: () => options.tokenBudget == null ? Infinity : Math.max(0, options.tokenBudget - state.spent),
+  });
+  const throwIfAborted = () => {
+    if (options.signal?.aborted) throw new Error("workflow aborted");
+  };
+  const agent = async (prompt: unknown, agentOptions: unknown = {}) => {
+    throwIfAborted();
+    if (budget.total !== null && budget.remaining() <= 0) throw new Error("workflow token budget exhausted");
+    const taskPrompt = requireString(prompt, "agent prompt");
+    const normalizedOptions = normalizeAgentOptions(agentOptions);
+    const assignedPhase = normalizedOptions.phase ?? state.currentPhase;
+    const requestedLabel = normalizedOptions.label?.trim();
+    const run = limiter(async () => {
+      const id = ++state.agentCount;
+      const label = requestedLabel || defaultAgentLabel(assignedPhase, id);
+      options.onAgentStart?.({ id, label, phase: assignedPhase, prompt: taskPrompt });
+      try {
+        throwIfAborted();
+        const result = await agentRunner.run(taskPrompt, {
+          label,
+          phase: assignedPhase,
+          schema: normalizedOptions.schema,
+          model: normalizedOptions.model,
+          agentType: normalizedOptions.agentType,
+          isolation: normalizedOptions.isolation,
+          signal: options.signal,
+          instructions: buildAgentInstructions(assignedPhase, normalizedOptions),
+          onActivity: options.onAgentActivity ? (metrics) => options.onAgentActivity?.(id, metrics) : undefined,
+        });
+        throwIfAborted();
+        state.spent += estimateTokens(result);
+        options.onAgentEnd?.({ id, label, phase: assignedPhase, result });
+        return result;
+      } catch (error) {
+        if (options.signal?.aborted) throw error;
+        log(`agent ${label} failed: ${error instanceof Error ? error.message : String(error)}`);
+        options.onAgentEnd?.({ id, label, phase: assignedPhase, result: null });
+        return null;
+      }
+    });
+    pendingAgentRuns.add(run);
+    run.then(() => pendingAgentRuns.delete(run), () => pendingAgentRuns.delete(run));
+    return run;
+  };
+  const parallel = async (thunks: unknown[]) => {
+    throwIfAborted();
+    if (!Array.isArray(thunks)) throw new TypeError("parallel() expects an array of functions");
+    if (thunks.some((thunk) => typeof thunk !== "function")) {
+      throw new TypeError("parallel() expects an array of functions, not promises. Wrap each call: () => agent(...)");
+    }
+    return Promise.all(thunks.map(async (thunk, index) => {
+      try {
+        return await (thunk as () => unknown)();
+      } catch (error) {
+        if (options.signal?.aborted) throw error;
+        log(`parallel[${index}] failed: ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+      }
+    }));
+  };
+  const pipeline = async (items: unknown[], ...stages: Array<(value: unknown, item: unknown, index: number) => unknown>) => {
+    throwIfAborted();
+    if (!Array.isArray(items)) throw new TypeError("pipeline() expects an array as the first argument");
+    if (stages.some((stage) => typeof stage !== "function")) {
+      throw new TypeError("pipeline() stages must be functions: pipeline(items, item => ..., result => ...)");
+    }
+    return Promise.all(items.map(async (item, index) => {
+      let value = item;
+      for (const stage of stages) {
+        try {
+          throwIfAborted();
+          value = await stage(value, item, index);
+          throwIfAborted();
+        } catch (error) {
+          if (options.signal?.aborted) throw error;
+          log(`pipeline[${index}] failed: ${error instanceof Error ? error.message : String(error)}`);
+          return null;
+        }
+      }
+      return value;
+    }));
+  };
+  const resolvedCwd = options.cwd ?? process.cwd();
+  const context = vm.createContext({
+    agent,
+    parallel,
+    pipeline,
+    log,
+    phase,
+    args: options.args,
+    cwd: resolvedCwd,
+    process: Object.freeze({ cwd: () => resolvedCwd }),
+    budget,
+    console: Object.freeze({
+      log,
+      info: log,
+      warn: (message: unknown) => log(`[warn] ${String(message)}`),
+      error: (message: unknown) => log(`[error] ${String(message)}`),
+    }),
+    JSON,
+    Math,
+    Array,
+    Object,
+    String,
+    Number,
+    Boolean,
+    Set,
+    Map,
+    Promise,
+  });
+  const wrapped = `(async () => {\n${body}\n})()`;
+  const result = await new vm.Script(wrapped, { filename: `${meta.name || "workflow"}.js` }).runInContext(context);
+  await Promise.allSettled([...pendingAgentRuns]);
+  assertStructuredCloneable(result, "workflow result");
+  return {
+    meta,
+    result: result as T,
+    logs: state.logs,
+    phases: state.phases,
+    agentCount: state.agentCount,
+    durationMs: Date.now() - started,
+  };
+}
+
+export function defaultConcurrency(): number {
+  const count = os.cpus()?.length;
+  return typeof count === "number" && count > 0 ? count : 8;
+}
+
+export function createLimiter(limit: number): <T>(fn: () => Promise<T>) => Promise<T> {
+  let active = 0;
+  const queue: Array<() => void> = [];
+  const next = () => {
+    active--;
+    queue.shift()?.();
+  };
+  return async <T>(fn: () => Promise<T>): Promise<T> => {
+    if (active >= limit) await new Promise<void>((resolve) => queue.push(resolve));
+    active++;
+    try {
+      return await fn();
+    } finally {
+      next();
+    }
+  };
+}
+
+export function requireString(value: unknown, name: string): string {
+  if (typeof value !== "string") throw new TypeError(`${name} must be a string`);
+  return value;
+}
+
+export function optionalString(value: unknown, name: string): string | undefined {
+  if (value === undefined) return undefined;
+  return requireString(value, name);
+}
+
+export function normalizeAgentOptions(value: unknown): AgentOptions {
+  if (!value || typeof value !== "object") throw new TypeError("agent options must be an object");
+  const options = value as Record<string, unknown>;
+  return {
+    ...options,
+    label: optionalString(options.label, "agent label"),
+    phase: optionalString(options.phase, "agent phase"),
+    model: optionalString(options.model, "agent model"),
+    isolation: options.isolation as "worktree" | undefined,
+    agentType: optionalString(options.agentType, "agent type"),
+  };
+}
+
+export function assertStructuredCloneable(value: unknown, name: string): void {
+  try {
+    structuredClone(value);
+  } catch (error) {
+    const detail = error instanceof Error ? ` ${error.message}` : "";
+    throw new Error(`${name} must be structured-cloneable; did you forget to await agent(), parallel(), or pipeline()?${detail}`);
+  }
+}
+
+export function defaultAgentLabel(phase: string | undefined, index: number): string {
+  return phase ? `${phase} agent ${index}` : `agent ${index}`;
+}
+
+export function buildAgentInstructions(phase: string | undefined, options: AgentOptions): string | undefined {
+  const lines: string[] = [];
+  if (phase) lines.push(`Workflow phase: ${phase}`);
+  if (options.agentType) lines.push(`Act as workflow subagent type: ${options.agentType}`);
+  if (options.isolation) lines.push(`Requested isolation: ${options.isolation}`);
+  if (options.model) lines.push(`Requested model: ${options.model}`);
+  return lines.length ? lines.join("\n") : undefined;
+}
+
+export function estimateTokens(value: unknown): number {
+  return Math.ceil(JSON.stringify(value ?? "").length / 4);
+}
+
+export function conductorFault(message: string): Error {
+  return new Error(message);
+}

package/src/workflow-engine/index.ts

@@ -0,0 +1,23 @@
+// @ts-nocheck
+// Type declarations recovered from dist/types (no runtime body)
+/**
+ * workflow-engine — the pure, network-free orchestration core for the `workflow`
+ * dynamic-workflow tool.
+ *
+ * This barrel exposes the engine subsystem only: the deterministic script
+ * parser, the `structured_output` capture tool, the progress snapshot model +
+ * text renderer, and the `runWorkflow` engine with its injectable
+ * {@link WorkflowAgentRunner} spawn seam. The card and console wiring (the real
+ * runner backed by a fresh framework `Agent`, the `tool_update` product signal,
+ * and `APP_NOVEL_CARDS` registration) live in stage 2 and consume these exports.
+ */
+export type { ParsedWorkflow, WorkflowMeta, WorkflowMetaPhase, } from "./parse.js";
+export { NONDETERMINISM_ERROR, parseWorkflowScript } from "./parse.js";
+export type { StructuredOutputCapture, StructuredOutputToolOptions, } from "./structured-output.js";
+export { createStructuredOutputTool } from "./structured-output.js";
+export type { WorkflowAgentSnapshot, WorkflowAgentStatus, WorkflowDisplayOptions, WorkflowSnapshot, } from "./display.js";
+export { createWorkflowSnapshot, preview, recomputeWorkflowSnapshot, renderWorkflowLines, renderWorkflowText, } from "./display.js";
+export type { AgentOptions, WorkflowAgentActivity, WorkflowAgentRunner, WorkflowAgentRunOptions, WorkflowRunOptions, WorkflowRunResult, } from "./engine.js";
+export { runWorkflow } from "./engine.js";
+export type { WorkflowAgentRunnerOptions, WorkflowSubAgent, WorkflowSpawnContext, } from "./agent-runner.js";
+export { createWorkflowAgentRunner } from "./agent-runner.js";

package/src/workflow-engine/parse.ts

@@ -0,0 +1,172 @@
+import vm from "node:vm";
+
+export interface WorkflowMetaPhase {
+  title: string;
+  detail?: string;
+  model?: string;
+}
+
+export interface WorkflowMeta {
+  name: string;
+  description: string;
+  whenToUse?: string;
+  phases?: WorkflowMetaPhase[];
+}
+
+export interface ParsedWorkflow {
+  meta: WorkflowMeta;
+  body: string;
+}
+
+export const NONDETERMINISM_ERROR =
+  "Workflow scripts must be deterministic: Date.now()/Math.random()/new Date() are unavailable";
+
+export const NONDETERMINISTIC_PATTERNS = [
+  /\bDate\s*\.\s*now\s*\(/,
+  /\bMath\s*\.\s*random\s*\(/,
+  /\bnew\s+Date\b/,
+];
+
+export function parseWorkflowScript(script: string): ParsedWorkflow {
+  if (typeof script !== "string") throw new TypeError("workflow script must be a string");
+  assertDeterministicSource(script);
+  const located = locateMetaExport(script);
+  const meta = evaluateMetaLiteral(located.literal);
+  validateMeta(meta);
+  return { meta, body: script.slice(0, located.start) + script.slice(located.end) };
+}
+
+export function assertDeterministicSource(script: string): void {
+  for (const pattern of NONDETERMINISTIC_PATTERNS) {
+    if (pattern.test(script)) throw new Error(NONDETERMINISM_ERROR);
+  }
+}
+
+export function locateMetaExport(script: string): { start: number; end: number; literal: string } {
+  const firstToken = skipTrivia(script, 0);
+  const header = /export\s+const\s+meta\s*=\s*/y;
+  header.lastIndex = firstToken;
+  const match = header.exec(script);
+  if (!match || match.index !== firstToken) {
+    throw new Error("`export const meta = { name, description }` must be the first statement in the script");
+  }
+  const braceStart = header.lastIndex;
+  if (script[braceStart] !== "{") {
+    throw new Error("meta export must be assigned a plain object literal: `export const meta = { … }`");
+  }
+  const braceEnd = matchBraces(script, braceStart);
+  const literal = script.slice(braceStart, braceEnd);
+  let end = braceEnd;
+  const afterBrace = skipTrivia(script, braceEnd);
+  if (script[afterBrace] === ";") end = afterBrace + 1;
+  return { start: firstToken, end, literal };
+}
+
+export function skipTrivia(source: string, from: number): number {
+  let i = from;
+  while (i < source.length) {
+    const ch = source[i];
+    if (ch === " " || ch === "\t" || ch === "\n" || ch === "\r" || ch === "\f" || ch === "\v") {
+      i++;
+      continue;
+    }
+    if (ch === "/" && source[i + 1] === "/") {
+      i += 2;
+      while (i < source.length && source[i] !== "\n") i++;
+      continue;
+    }
+    if (ch === "/" && source[i + 1] === "*") {
+      i += 2;
+      while (i < source.length && !(source[i] === "*" && source[i + 1] === "/")) i++;
+      i += 2;
+      continue;
+    }
+    break;
+  }
+  return i;
+}
+
+export function matchBraces(source: string, open: number): number {
+  let depth = 0;
+  let i = open;
+  while (i < source.length) {
+    const ch = source[i];
+    if (ch === "/" && source[i + 1] === "/") {
+      i += 2;
+      while (i < source.length && source[i] !== "\n") i++;
+      continue;
+    }
+    if (ch === "/" && source[i + 1] === "*") {
+      i += 2;
+      while (i < source.length && !(source[i] === "*" && source[i + 1] === "/")) i++;
+      i += 2;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") {
+      i = skipStringLike(source, i, ch);
+      continue;
+    }
+    if (ch === "{") depth++;
+    else if (ch === "}") {
+      depth--;
+      if (depth === 0) return i + 1;
+    }
+    i++;
+  }
+  throw new Error("meta object literal is not closed: missing `}`");
+}
+
+export function skipStringLike(source: string, start: number, quote: string): number {
+  let i = start + 1;
+  while (i < source.length) {
+    const ch = source[i];
+    if (ch === "\\") {
+      i += 2;
+      continue;
+    }
+    if (quote === "`" && ch === "$" && source[i + 1] === "{") {
+      let depth = 1;
+      i += 2;
+      while (i < source.length && depth > 0) {
+        if (source[i] === "{") depth++;
+        else if (source[i] === "}") depth--;
+        i++;
+      }
+      continue;
+    }
+    if (ch === quote) return i + 1;
+    i++;
+  }
+  throw new Error("unterminated string in meta object literal");
+}
+
+export function evaluateMetaLiteral(literal: string): unknown {
+  const context = vm.createContext(Object.create(null));
+  try {
+    return new vm.Script(`(${literal})`, { filename: "workflow.meta.js" }).runInContext(context, { timeout: 1000 });
+  } catch (error) {
+    const detail = error instanceof Error ? `: ${error.message}` : "";
+    throw new Error(`meta export must be a plain object literal${detail}`);
+  }
+}
+
+export function validateMeta(meta: unknown): asserts meta is WorkflowMeta {
+  if (!meta || typeof meta !== "object") throw new Error("meta must be an object");
+  const value = meta as Record<string, unknown>;
+  if (typeof value.name !== "string" || !value.name.trim()) throw new Error("meta.name must be a non-empty string");
+  if (typeof value.description !== "string" || !value.description.trim()) {
+    throw new Error("meta.description must be a non-empty string");
+  }
+  if (value.whenToUse !== undefined && typeof value.whenToUse !== "string") throw new Error("meta.whenToUse must be a string");
+  if (value.phases !== undefined) {
+    if (!Array.isArray(value.phases)) throw new Error("meta.phases must be an array");
+    for (const phase of value.phases) {
+      if (!phase || typeof phase !== "object" || typeof phase.title !== "string") {
+        throw new Error("each meta phase must have a title string");
+      }
+      if (phase.detail !== undefined && typeof phase.detail !== "string") {
+        throw new Error("meta phase detail must be a string");
+      }
+    }
+  }
+}

package/src/workflow-engine/structured-output.ts

@@ -0,0 +1,35 @@
+import type { Static, TSchema } from "@sinclair/typebox";
+import type { AgentTool } from "../capability-deck/index.js";
+
+export interface StructuredOutputCapture<T = unknown> {
+  value: T | undefined;
+  called: boolean;
+}
+
+export interface StructuredOutputToolOptions<TSchemaDef extends TSchema> {
+  schema: TSchemaDef;
+  capture: StructuredOutputCapture<Static<TSchemaDef>>;
+  name?: string;
+}
+
+export function createStructuredOutputTool<TSchemaDef extends TSchema>({
+  schema,
+  capture,
+  name = "structured_output",
+}: StructuredOutputToolOptions<TSchemaDef>): AgentTool<TSchemaDef, Static<TSchemaDef>> {
+  return {
+    name,
+    label: "Structured Output",
+    description: "Return the final machine-readable result for this subagent task.",
+    readOnly: true,
+    parameters: schema,
+    async execute(_toolCallId, params) {
+      capture.value = params;
+      capture.called = true;
+      return {
+        content: [{ type: "text", text: "Structured output received." }],
+        details: params,
+      };
+    },
+  };
+}

package/src/workspace/brand.ts

@@ -0,0 +1,29 @@
+/**
+ * Brand record — the single source of truth for every identity literal.
+ *
+ * One frozen {@link Brand} value. Nothing else in the app hard-codes the
+ * product name, the profile-directory leaf, the bin names, the env-var
+ * namespace, or the share-viewer origin.
+ */
+import type { Brand } from "../boot/contract.js";
+
+/**
+ * The concrete indusagi identity.
+ */
+export const BRAND: Brand = Object.freeze({
+  name: "indusagi",
+  label: "indusagi",
+  profileDirName: ".indusagi",
+  stateDirName: "agent",
+  binNames: ["indus", "indusagi"],
+  envPrefix: "INDUSAGI",
+  envProfileDir: "INDUSAGI_CODING_AGENT_DIR",
+  envDebug: "INDUSAGI_DEBUG",
+  envShareViewer: "INDUSAGI_SHARE_VIEWER_URL",
+  shareViewerUrl: "https://buildwithindusagi.ai/session/",
+});
+
+/**
+ * The product version — printed by `--version` and shown on the startup banner.
+ */
+export const VERSION = "0.2.10";

package/src/workspace/index.ts

@@ -0,0 +1,18 @@
+// @ts-nocheck
+// Type declarations recovered from dist/types (no runtime body)
+/**
+ * Workspace subsystem — public barrel.
+ *
+ * One import site for the keyed Workspace Locator, the concrete {@link BRAND}
+ * record, and the runtime/packaging detection. Boot stages depend on this
+ * module rather than reaching into the individual files.
+ */
+export { BRAND, VERSION } from "./brand.js";
+export { createWorkspace, ensureDirs, type WorkspaceOverrides } from "./locator.js";
+export {
+  isPackagedBinary,
+  resolvePackageRoot,
+  detectPackagingFromModuleUrl,
+  type Packaging,
+} from "./runtime-detect.js";
+export type { Brand, Workspace } from "../boot/contract.js";

package/src/workspace/locator.ts

@@ -0,0 +1,103 @@
+/**
+ * Workspace Locator — turns the active {@link Brand} plus the environment into a
+ * single, fully-resolved {@link Workspace} record of absolute paths.
+ */
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import type { Brand, Workspace } from "../boot/contract.js";
+import { BRAND } from "./brand.js";
+
+export interface WorkspaceOverrides {
+  /** User home directory; defaults to {@link homedir}. */
+  readonly home?: string;
+  /** Working directory the resolution is anchored to; defaults to `process.cwd()`. */
+  readonly cwd?: string;
+  /** Environment to read the profile-dir override from; defaults to {@link process.env}. */
+  readonly env?: NodeJS.ProcessEnv;
+  /** Brand whose directory names drive the layout; defaults to {@link BRAND}. */
+  readonly brand?: Brand;
+}
+
+const LAYOUT: Record<keyof Workspace, string[]> = {
+  profileDir: [],
+  settingsPath: ["settings.json"],
+  authPath: ["auth.json"],
+  sessionsDir: ["sessions"],
+  modelsPath: ["models.json"],
+  toolsDir: ["bin"],
+  binDir: ["bin"],
+  promptsDir: ["prompts"],
+  themesDir: ["themes"],
+  exportTemplateDir: ["export-template"],
+  debugLogPath: ["debug.log"],
+  mcpConfigPath: ["mcp-servers.json"],
+  memoryConfigPath: ["memory.json"],
+  composioConfigPath: ["composio.json"],
+  zohoConfigPath: ["zoho.json"],
+  memoryDbPath: ["memory.db"],
+};
+
+const DIRECTORY_KEYS: Array<keyof Workspace> = [
+  "profileDir",
+  "sessionsDir",
+  "toolsDir",
+  "binDir",
+  "promptsDir",
+  "themesDir",
+  "exportTemplateDir",
+];
+
+function resolveProfileRoot(
+  brand: Brand,
+  home: string,
+  cwd: string,
+  env: NodeJS.ProcessEnv,
+): string {
+  const override = env[brand.envProfileDir]?.trim();
+  if (override) {
+    return expandHome(override, home, cwd);
+  }
+  return join(home, brand.profileDirName, brand.stateDirName);
+}
+
+function expandHome(rawPath: string, home: string, cwd: string): string {
+  if (rawPath === "~") {
+    return home;
+  }
+  if (rawPath.startsWith("~/") || rawPath.startsWith("~\\")) {
+    return join(home, rawPath.slice(2));
+  }
+  if (isAbsolute(rawPath)) {
+    return rawPath;
+  }
+  return resolve(cwd, rawPath);
+}
+
+/**
+ * Build the fully-resolved {@link Workspace} for the active brand and
+ * environment.
+ */
+export function createWorkspace(overrides: WorkspaceOverrides = {}): Workspace {
+  const brand = overrides.brand ?? BRAND;
+  const home = overrides.home ?? homedir();
+  const cwd = overrides.cwd ?? process.cwd();
+  const env = overrides.env ?? process.env;
+  const profileRoot = resolveProfileRoot(brand, home, cwd, env);
+  const entries = Object.keys(LAYOUT).map((key) => {
+    const segments = LAYOUT[key as keyof Workspace];
+    const absolute = segments.length === 0 ? profileRoot : join(profileRoot, ...segments);
+    return [key, absolute];
+  });
+  return Object.freeze(Object.fromEntries(entries)) as Workspace;
+}
+
+/**
+ * Create every directory the workspace expects, idempotently.
+ */
+export function ensureDirs(workspace: Workspace): Workspace {
+  for (const key of DIRECTORY_KEYS) {
+    mkdirSync(workspace[key], { recursive: true });
+  }
+  return workspace;
+}