@geraldmaron/construct 1.2.2 → 1.2.3

package/apps/chat/engine/tools/permission.mjs

@@ -0,0 +1,54 @@
+/**
+ * apps/chat/engine/tools/permission.mjs — the permission and sandbox gate for the
+ * owned loop's tools.
+ *
+ * Owning the loop means Construct, not a host, decides whether a tool runs. This
+ * gate reuses the host-agnostic decision vocabulary ADR-0040 defined
+ * (allow | allow_always | reject) and the sandbox levels from lib/chat/config.mjs
+ * (read-only, workspace-write, danger-full-access). Read-only tools (read, grep,
+ * glob) always pass; mutating tools (write, edit, shell) are gated by the sandbox
+ * level and the current permission mode, deferring to an interactive
+ * `requestPermission` handler only in `ask` mode. `allow_always` is sticky for the
+ * rest of the session so a user is not re-prompted per call.
+ *
+ * `allowOutside` (escape the workspace root) is granted only under
+ * danger-full-access; every other level keeps tools inside the workspace, which
+ * the primitives enforce independently.
+ */
+
+export const READ_ONLY_TOOLS = new Set(['read', 'grep', 'glob']);
+export const MUTATING_TOOLS = new Set(['write', 'edit', 'shell']);
+
+export function createPermissionGate({
+  getSandbox = () => null,
+  getPermissionMode = () => 'allow_once',
+  requestPermission = null,
+} = {}) {
+  let alwaysAllowed = false;
+
+  async function check(toolName, input = {}) {
+    const sandbox = getSandbox() || 'workspace-write';
+    const allowOutside = sandbox === 'danger-full-access';
+
+    if (READ_ONLY_TOOLS.has(toolName)) return { allowed: true, allowOutside };
+
+    if (sandbox === 'read-only') {
+      return { allowed: false, allowOutside, reason: 'sandbox is read-only; mutating tools are disabled (change with /set sandbox workspace-write)' };
+    }
+
+    if (alwaysAllowed) return { allowed: true, allowOutside };
+
+    const mode = getPermissionMode() || 'allow_once';
+    if (mode === 'reject') return { allowed: false, allowOutside, reason: 'permission mode is reject' };
+    if (mode === 'allow_always') { alwaysAllowed = true; return { allowed: true, allowOutside }; }
+    if (mode === 'allow_once') return { allowed: true, allowOutside };
+
+    // ask mode: defer to the interactive handler, mapping its decision back.
+    const decision = requestPermission ? await requestPermission({ tool: toolName, input }) : 'allow';
+    if (decision === 'reject') return { allowed: false, allowOutside, reason: 'denied by user' };
+    if (decision === 'allow_always') { alwaysAllowed = true; return { allowed: true, allowOutside }; }
+    return { allowed: true, allowOutside };
+  }
+
+  return { check, get alwaysAllowed() { return alwaysAllowed; } };
+}

package/apps/chat/engine/tools/primitives.mjs

@@ -0,0 +1,180 @@
+/**
+ * apps/chat/engine/tools/primitives.mjs — zero-dep executors for the owned loop's
+ * agent tools (read, write, edit, glob, grep, shell).
+ *
+ * These are the side-effecting primitives the loop calls; they are pure Node so
+ * they are fully testable in a tmpdir with no model, network, or SDK. Path safety
+ * is enforced here: every path resolves inside the workspace root unless the caller
+ * passes `allowOutside` (set only by the danger-full-access sandbox). Search tools
+ * walk the tree with a hard result/size cap and skip the usual heavy/ignored dirs
+ * so a grep never hangs the loop. Shell reuses the bounded worker runner
+ * (lib/worker/run.mjs) for the timeout + path policy already proven there.
+ *
+ * Every function returns a structured, JSON-serializable result (never throws for
+ * an ordinary "not found"/"no match" outcome) so the result maps cleanly onto a
+ * tool_update event and back to the model.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { runJob } from '../../../../lib/worker/run.mjs';
+
+const IGNORED_DIRS = new Set(['node_modules', '.git', '.cx', 'dist', 'build', '.next', 'coverage', '.cache']);
+const MAX_READ_BYTES = 256 * 1024;
+const MAX_WALK_FILES = 20000;
+
+function resolveInside(cwd, target, { allowOutside = false } = {}) {
+  const root = path.resolve(cwd);
+  const resolved = path.resolve(root, target || '.');
+  if (!allowOutside && resolved !== root && !resolved.startsWith(`${root}${path.sep}`)) {
+    const err = new Error(`path '${target}' is outside the workspace; not permitted under the current sandbox`);
+    err.code = 'PATH_OUTSIDE_WORKSPACE';
+    throw err;
+  }
+  return resolved;
+}
+
+export function readFileTool({ cwd, path: target, maxBytes = MAX_READ_BYTES, allowOutside = false } = {}) {
+  const file = resolveInside(cwd, target, { allowOutside });
+  if (!fs.existsSync(file)) return { ok: false, error: `no such file: ${target}` };
+  const stat = fs.statSync(file);
+  if (stat.isDirectory()) return { ok: false, error: `${target} is a directory` };
+  const buf = fs.readFileSync(file);
+  const truncated = buf.length > maxBytes;
+  return { ok: true, path: target, bytes: stat.size, truncated, content: buf.slice(0, maxBytes).toString('utf8') };
+}
+
+export function writeFileTool({ cwd, path: target, content = '', allowOutside = false } = {}) {
+  const file = resolveInside(cwd, target, { allowOutside });
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, content, 'utf8');
+  return { ok: true, path: target, bytes: Buffer.byteLength(content, 'utf8') };
+}
+
+export function editFileTool({ cwd, path: target, oldString, newString = '', replaceAll = false, allowOutside = false } = {}) {
+  const file = resolveInside(cwd, target, { allowOutside });
+  if (!fs.existsSync(file)) return { ok: false, error: `no such file: ${target}` };
+  if (typeof oldString !== 'string' || oldString.length === 0) return { ok: false, error: 'oldString is required and must be non-empty' };
+  const before = fs.readFileSync(file, 'utf8');
+  const occurrences = before.split(oldString).length - 1;
+  if (occurrences === 0) return { ok: false, error: 'oldString not found in file' };
+  if (occurrences > 1 && !replaceAll) return { ok: false, error: `oldString is not unique (${occurrences} matches); pass replaceAll or add more context` };
+  const after = replaceAll ? before.split(oldString).join(newString) : before.replace(oldString, newString);
+  fs.writeFileSync(file, after, 'utf8');
+  return { ok: true, path: target, replacements: replaceAll ? occurrences : 1 };
+}
+
+// Bounded depth-first walk yielding workspace-relative file paths, skipping the
+// ignored dirs. Caps the number of files visited so a pathological tree cannot
+// stall the loop.
+
+function* walkFiles(root) {
+  const stack = [root];
+  let visited = 0;
+  while (stack.length) {
+    const dir = stack.pop();
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (IGNORED_DIRS.has(entry.name) || entry.name.startsWith('.')) continue;
+        stack.push(full);
+      } else if (entry.isFile()) {
+        if (++visited > MAX_WALK_FILES) return;
+        yield full;
+      }
+    }
+  }
+}
+
+// Translate a simple glob ("**/*.mjs", "src/*.ts", "lib/**") into a RegExp. Only
+// the common operators are supported (no brace expansion), which covers what the
+// loop needs without pulling a glob dependency.
+
+function globToRegExp(pattern) {
+  let re = '';
+  for (let i = 0; i < pattern.length; i++) {
+    const c = pattern[i];
+    if (c === '*') {
+      if (pattern[i + 1] === '*') { re += '.*'; i++; if (pattern[i + 1] === '/') i++; }
+      else re += '[^/]*';
+    } else if (c === '?') re += '[^/]';
+    else if ('.+^${}()|[]\\'.includes(c)) re += `\\${c}`;
+    else re += c;
+  }
+  return new RegExp(`^${re}$`);
+}
+
+export function globTool({ cwd, pattern, limit = 200, allowOutside = false } = {}) {
+  const root = resolveInside(cwd, '.', { allowOutside });
+  if (!pattern) return { ok: false, error: 'pattern is required' };
+  const rx = globToRegExp(pattern);
+  const matches = [];
+  for (const file of walkFiles(root)) {
+    const rel = path.relative(root, file);
+    if (rx.test(rel)) {
+      matches.push(rel);
+      if (matches.length >= limit) break;
+    }
+  }
+  return { ok: true, pattern, matches, truncated: matches.length >= limit };
+}
+
+export function grepTool({ cwd, pattern, glob = null, limit = 200, caseInsensitive = false, allowOutside = false } = {}) {
+  const root = resolveInside(cwd, '.', { allowOutside });
+  if (!pattern) return { ok: false, error: 'pattern is required' };
+  let rx;
+  try { rx = new RegExp(pattern, caseInsensitive ? 'i' : ''); } catch (err) { return { ok: false, error: `invalid pattern: ${err.message}` }; }
+  const globRx = glob ? globToRegExp(glob) : null;
+  const matches = [];
+  for (const file of walkFiles(root)) {
+    const rel = path.relative(root, file);
+    if (globRx && !globRx.test(rel)) continue;
+    let text;
+    try {
+      const stat = fs.statSync(file);
+      if (stat.size > MAX_READ_BYTES) continue;
+      text = fs.readFileSync(file, 'utf8');
+    } catch { continue; }
+    if (text.includes('\u0000')) continue;
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      if (rx.test(lines[i])) {
+        matches.push({ file: rel, line: i + 1, text: lines[i].slice(0, 300) });
+        if (matches.length >= limit) return { ok: true, pattern, matches, truncated: true };
+      }
+    }
+  }
+  return { ok: true, pattern, matches, truncated: false };
+}
+
+export async function shellTool({ cwd, command, timeoutSeconds = 60, allowOutside = false } = {}) {
+  if (!command || typeof command !== 'string') return { ok: false, error: 'command is required' };
+  const root = path.resolve(cwd);
+  const result = await runJob({
+    rootDir: root,
+    job: {
+      jobId: `chat-${randomUUID()}`,
+      command,
+      timeoutSeconds,
+      workspaceRef: root,
+      allowedPaths: allowOutside ? [] : [root],
+    },
+  });
+  let stdout = '';
+  let stderr = '';
+  try { stdout = fs.readFileSync(result.stdoutPath, 'utf8'); } catch { /* no stdout */ }
+  try { stderr = fs.readFileSync(result.stderrPath, 'utf8'); } catch { /* no stderr */ }
+  return {
+    ok: result.status === 'passed',
+    status: result.status,
+    exitCode: result.exitCode,
+    durationMs: result.durationMs,
+    stdout: stdout.slice(0, MAX_READ_BYTES),
+    stderr: stderr.slice(0, MAX_READ_BYTES),
+  };
+}
+
+export const __test__ = { resolveInside, globToRegExp };

package/apps/chat/engine/tools/registry.mjs

@@ -0,0 +1,122 @@
+/**
+ * apps/chat/engine/tools/registry.mjs — builds the owned loop's tool set as Vercel
+ * AI SDK tools, gated by the permission/sandbox policy.
+ *
+ * Each tool wraps a zero-dep primitive (primitives.mjs) behind the permission gate
+ * (permission.mjs): the gate runs first, and a denial returns a structured result
+ * the model can read rather than throwing, so the loop degrades gracefully instead
+ * of crashing on a blocked action. A single `construct_tool` bridges the loop to
+ * Construct's existing MCP tool surface via dispatchToolByName (mirroring the MCP
+ * `construct_call` meta-tool), so the loop reaches knowledge search, skills, and
+ * orchestration policy without re-declaring 60+ schemas here.
+ *
+ * `ai` and `zod` are imported lazily and only here, so the rest of the engine and
+ * all of its tests stay free of the optional dependencies.
+ */
+
+import {
+  readFileTool, writeFileTool, editFileTool, globTool, grepTool, shellTool,
+} from './primitives.mjs';
+import { createPermissionGate } from './permission.mjs';
+
+function denied(reason) {
+  return { ok: false, denied: true, error: reason };
+}
+
+export async function buildAgentTools({ env = process.env, cwd = process.cwd(), handlers = {}, only = null } = {}) {
+  const { tool } = await import('ai');
+  const { z } = await import('zod');
+
+  const gate = createPermissionGate({
+    getSandbox: handlers.getSandbox || (() => null),
+    getPermissionMode: handlers.getPermissionMode || (() => 'allow_once'),
+    requestPermission: handlers.requestPermission || null,
+  });
+
+  const defs = {
+    read: tool({
+      description: 'Read a UTF-8 text file from the workspace.',
+      inputSchema: z.object({ path: z.string().describe('workspace-relative file path') }),
+      execute: async ({ path: p }) => {
+        const verdict = await gate.check('read', { path: p });
+        if (!verdict.allowed) return denied(verdict.reason);
+        return readFileTool({ cwd, path: p, allowOutside: verdict.allowOutside });
+      },
+    }),
+    glob: tool({
+      description: 'Find files by glob pattern (supports * ** ?).',
+      inputSchema: z.object({ pattern: z.string(), limit: z.number().int().positive().max(1000).optional() }),
+      execute: async ({ pattern, limit }) => {
+        const verdict = await gate.check('glob', { pattern });
+        if (!verdict.allowed) return denied(verdict.reason);
+        return globTool({ cwd, pattern, limit, allowOutside: verdict.allowOutside });
+      },
+    }),
+    grep: tool({
+      description: 'Search file contents by regular expression, optionally filtered by a glob.',
+      inputSchema: z.object({
+        pattern: z.string(),
+        glob: z.string().optional(),
+        caseInsensitive: z.boolean().optional(),
+        limit: z.number().int().positive().max(1000).optional(),
+      }),
+      execute: async ({ pattern, glob, caseInsensitive, limit }) => {
+        const verdict = await gate.check('grep', { pattern });
+        if (!verdict.allowed) return denied(verdict.reason);
+        return grepTool({ cwd, pattern, glob, caseInsensitive, limit, allowOutside: verdict.allowOutside });
+      },
+    }),
+    write: tool({
+      description: 'Create or overwrite a workspace file with the given content.',
+      inputSchema: z.object({ path: z.string(), content: z.string() }),
+      execute: async ({ path: p, content }) => {
+        const verdict = await gate.check('write', { path: p });
+        if (!verdict.allowed) return denied(verdict.reason);
+        return writeFileTool({ cwd, path: p, content, allowOutside: verdict.allowOutside });
+      },
+    }),
+    edit: tool({
+      description: 'Replace an exact string in a workspace file. oldString must be unique unless replaceAll is set.',
+      inputSchema: z.object({
+        path: z.string(),
+        oldString: z.string(),
+        newString: z.string(),
+        replaceAll: z.boolean().optional(),
+      }),
+      execute: async ({ path: p, oldString, newString, replaceAll }) => {
+        const verdict = await gate.check('edit', { path: p });
+        if (!verdict.allowed) return denied(verdict.reason);
+        return editFileTool({ cwd, path: p, oldString, newString, replaceAll, allowOutside: verdict.allowOutside });
+      },
+    }),
+    shell: tool({
+      description: 'Run a bounded shell command in the workspace with a timeout.',
+      inputSchema: z.object({ command: z.string(), timeoutSeconds: z.number().int().positive().max(600).optional() }),
+      execute: async ({ command, timeoutSeconds }) => {
+        const verdict = await gate.check('shell', { command });
+        if (!verdict.allowed) return denied(verdict.reason);
+        return shellTool({ cwd, command, timeoutSeconds, allowOutside: verdict.allowOutside });
+      },
+    }),
+    construct_tool: tool({
+      description: 'Call a Construct MCP tool by name (e.g. knowledge_search, search_skills, orchestration_policy). Returns the tool result.',
+      inputSchema: z.object({ name: z.string(), args: z.record(z.string(), z.any()).optional() }),
+      execute: async ({ name, args }) => {
+        try {
+          const { dispatchToolByName } = await import('../../../../lib/mcp/server.mjs');
+          const result = await dispatchToolByName(name, args || {});
+          return { ok: true, name, result };
+        } catch (err) {
+          return { ok: false, name, error: err?.message || String(err) };
+        }
+      },
+    }),
+  };
+
+  if (!Array.isArray(only) || only.length === 0) return defs;
+  const filtered = {};
+  for (const name of only) if (defs[name]) filtered[name] = defs[name];
+  return filtered;
+}
+
+export const AGENT_TOOL_NAMES = ['read', 'glob', 'grep', 'write', 'edit', 'shell', 'construct_tool'];

package/apps/chat/engine/turn-controls.mjs

@@ -0,0 +1,70 @@
+/**
+ * apps/chat/engine/turn-controls.mjs — resolve one turn's execution controls from
+ * the compiled execution policy (construct-rv2x).
+ *
+ * The owned-loop engine (ai-sdk-agent.mjs) calls this once per turn to turn a
+ * capability profile plus the turn overlay into the concrete knobs streamText
+ * needs: the step cap, the output-token cap, caching eligibility, and the tool-
+ * group / schema budget, plus the continuation/compaction budget the session uses
+ * to decide when to compact context (construct-6zga.1.9). The capability profile
+ * is resolved from the active model id, so a mid-session model switch re-derives
+ * the envelope.
+ *
+ * Behavior preservation is the contract: this never throws and never returns a
+ * tighter envelope than today for a hosted-direct model. hosted-direct keeps the
+ * legacy step cap, the full tool set, and unbounded output; every other class
+ * enforces its compiled budget. An explicit CX_CHAT_MAX_STEPS operator override
+ * wins over the policy's step cap. Any failure in policy resolution falls back to
+ * the legacy envelope (16 steps, full tool set, no cap, no caching) so a policy
+ * bug can never break a chat turn.
+ */
+
+import { resolveExecutionCapabilityProfile } from '../../../lib/models/execution-capability-profile.mjs';
+import { compilePolicyFromOverlay } from '../../../lib/models/execution-policy.mjs';
+import { continuationBudgetFromPolicy } from '../../../lib/chat/context-continuation.mjs';
+
+const LEGACY_STEP_CAP = 16;
+
+const LEGACY_CONTROLS = Object.freeze({
+  policy: null,
+  iterations: LEGACY_STEP_CAP,
+  outputCap: null,
+  cacheEligible: false,
+  allowedToolGroups: null,
+  maxToolSchemas: Infinity,
+  degraded: false,
+  continuation: Object.freeze({ triggerTokens: null, triggerRatio: null }),
+});
+
+function legacyControls() {
+  return { ...LEGACY_CONTROLS };
+}
+
+export function resolveTurnControls({ model = null, turnOverlay = null, env = {} } = {}) {
+  try {
+    const profile = resolveExecutionCapabilityProfile({ model });
+    const toolFailure = turnOverlay?.toolFailure === true;
+    const policy = compilePolicyFromOverlay({ profile, overlay: turnOverlay, toolFailure });
+
+    const envSteps = Number(env?.CX_CHAT_MAX_STEPS);
+    const iterations = envSteps > 0 ? Math.floor(envSteps) : policy.tools.maxToolIterations;
+
+    // hosted-direct is the mandated default path: keep today's unbounded output
+    // until live-probe evidence supersedes the compatibility_fallback tier. Every
+    // other class enforces its compiled output budget.
+    const outputCap = policy.source.capabilityClass === 'hosted-direct' ? null : policy.output.outputTokenBudget;
+
+    return {
+      policy,
+      iterations,
+      outputCap,
+      cacheEligible: policy.caching.eligible === true,
+      allowedToolGroups: policy.tools.allowedToolGroups,
+      maxToolSchemas: policy.tools.maxToolSchemas,
+      degraded: policy.degradedMode === true,
+      continuation: continuationBudgetFromPolicy(policy),
+    };
+  } catch {
+    return legacyControls();
+  }
+}

package/bin/construct

@@ -653,6 +653,21 @@ async function cmdDoctor() {
     );
   }
 
+  // Mirror model tier overrides stranded in the pre-XDG legacy config forward
+  // before resolving tiers, so an install upgraded across the XDG move reports
+  // configured without a manual copy. Applied to process.env too so the check
+  // below sees the just-migrated values in the same run.
+  try {
+    const { migrateLegacyModelConfig } = await import('../lib/config/legacy-config-migration.mjs');
+    const migration = migrateLegacyModelConfig({ homeDir: HOME });
+    if (migration.performed) {
+      Object.assign(process.env, migration.migrated);
+      println(`  fix: migrated ${Object.keys(migration.migrated).join(', ')} from ${migration.legacyPath} → ${migration.xdgPath}`);
+    }
+  } catch (err) {
+    add(`Models — legacy config migration failed: ${err.message}`, false, true);
+  }
+
   // Tier model selection. Construct ships with no default — at least
   // one tier must be configured (registry.json primary OR CX_MODEL_*
   // env override) before any LLM-backed workflow can run.
@@ -3773,7 +3788,15 @@ async function cmdOrchestrate(args) {
 }
 
 async function cmdModels(args) {
-  if (args[0] === 'resolve') {
+  const envPath = getUserEnvPath(HOME);
+  const sub = args[0] && !args[0].startsWith('-') ? args[0] : null;
+  const KNOWN_SUBCOMMANDS = new Set(['list', 'set', 'free', 'reset', 'resolve']);
+  if (sub && !KNOWN_SUBCOMMANDS.has(sub)) {
+    errorln(`Unknown models subcommand: ${sub}. Run \`construct models --help\` for the supported set.`);
+    process.exit(1);
+  }
+
+  if (sub === 'resolve') {
     const flag = (name) => { const i = args.indexOf(name); return i !== -1 ? args[i + 1] : undefined; };
     const { resolveEmbeddedModel } = await import('../lib/embedded-contract/model-resolve.mjs');
     const { wrapContractResult } = await import('../lib/embedded-contract/envelope.mjs');
@@ -3790,21 +3813,37 @@ async function cmdModels(args) {
     println(JSON.stringify(envelope, null, 2));
     return;
   }
+  // Legacy flag forms stay as compatibility aliases for the documented
+  // subcommands. Each emits a one-line deprecation notice on stderr so stdout
+  // stays clean while operators migrate to `models set|reset|free`.
   const tier = args.find((arg) => arg.startsWith('--tier='))?.split('=')[1] ?? '';
-  const setModel = args.find((arg) => arg.startsWith('--set='))?.split('=')[1] ?? '';
-  const envPath = getUserEnvPath(HOME);
-  if (args.includes('--reset')) {
+  const modelFlag = args.find((arg) => arg.startsWith('--model='))?.split('=')[1];
+  const legacySetFlag = args.find((arg) => arg.startsWith('--set='))?.split('=')[1];
+  const setModel = modelFlag ?? legacySetFlag ?? '';
+
+  if (sub === 'reset' || args.includes('--reset')) {
+    if (sub !== 'reset') errorln('Note: `construct models --reset` is a deprecated alias for `construct models reset`.');
     resetEnv(envPath);
-    println('Removed CX_MODEL_* overrides from ~/.construct/config.env.');
+    println(`Removed CX_MODEL_* overrides from ${envPath}.`);
     await cmdSync([]);
     return;
   }
-  if (tier && setModel) {
+  if (sub === 'set' || (sub === null && tier && setModel)) {
+    if (!tier || !setModel) {
+      errorln('Usage: construct models set --tier=<reasoning|standard|fast> --model=<provider/model-id>');
+      process.exit(1);
+    }
+    if (modelFlag === undefined && legacySetFlag !== undefined) {
+      errorln('Note: `--set=<model>` is a deprecated alias for `--model=<model>`.');
+    }
+    if (sub === null) {
+      errorln('Note: `construct models --tier=… --set=…` is a deprecated alias for `construct models set --tier=… --model=…`.');
+    }
     const registry = JSON.parse(fs.readFileSync(path.join(ROOT_DIR, 'specialists', 'registry.json'), 'utf8'));
     const preferFree = args.includes('--prefer-free');
     const preferFreeSameFamily = args.includes('--prefer-free-same-family');
     const inferred = setModelWithTierInference(envPath, tier, setModel, registry.models ?? {}, { preferFree, preferFreeSameFamily });
-    println(`Set ${tier} -> ${setModel} in ~/.construct/config.env`);
+    println(`Set ${tier} -> ${setModel} in ${envPath}`);
     if (preferFreeSameFamily) println('Prefer-free-same-family mode: enabled');
     if (preferFree) println('Prefer-free mode: enabled');
     println(`Resolved tier set:`);
@@ -3814,7 +3853,8 @@ async function cmdModels(args) {
     await cmdSync([]);
     return;
   }
-  if (args.includes('--poll')) {
+  if (sub === 'free' || args.includes('--poll')) {
+    if (sub !== 'free') errorln('Note: `construct models --poll` is a deprecated alias for `construct models free`.');
     const apiKey = process.env.OPENROUTER_API_KEY || readOpenRouterApiKeyFromOpenCodeConfig();
     if (!apiKey) {
       errorln('Error: no OpenRouter API key found in OPENROUTER_API_KEY or OpenCode config.');
@@ -3841,7 +3881,7 @@ async function cmdModels(args) {
       if (id) selections[currentTier] = id;
     }
     applyToEnv(envPath, selections);
-    println('Written to ~/.construct/config.env. Running construct sync...');
+    println(`Written to ${envPath}. Running construct sync...`);
     await cmdSync([]);
     return;
   }
@@ -3878,12 +3918,12 @@ async function cmdModels(args) {
     for (const [tier, model] of Object.entries(selections)) {
       println(`  ${tier.padEnd(11)} ${model}`);
     }
-    println('Written to ~/.construct/config.env. Running construct sync...');
+    println(`Written to ${envPath}. Running construct sync...`);
     setCheapestProviderPreference(envPath, true);
     await cmdSync([]);
     return;
   }
-  if (args.includes('--list') || args[0] === 'list') {
+  if (args.includes('--list') || sub === 'list') {
     const { getProviderModelCatalog } = await import('../lib/model-router.mjs');
     const { listChatModels } = await import('../apps/chat/engine/models.mjs');
     const catalog = getProviderModelCatalog({ env: process.env, cwd: process.cwd() });
@@ -3913,7 +3953,7 @@ async function cmdModels(args) {
     println('No tier has a model selected. Construct ships with no default.');
     println('Pick one of:');
     println('  • Dashboard → Models page (single source of truth)');
-    println('  • construct models --set=<provider/model-id> --tier=reasoning|standard|fast');
+    println('  • construct models set --tier=<reasoning|standard|fast> --model=<provider/model-id>');
     println('  • construct models --apply           Poll OpenRouter free catalog and seed all tiers');
   }
 }

package/lib/cli-commands.mjs

@@ -429,14 +429,12 @@ export const CLI_COMMANDS = [
     category: 'Models & Integrations',
     core: false,
     description: 'Show or update model tier assignments',
-    usage: 'construct models <list|set|free|reset|usage|cost|resolve>',
+    usage: 'construct models <list|set|free|reset|resolve>',
     subcommands: [
       { name: 'list', desc: 'Show current tier assignments' },
       { name: 'set --tier=<reasoning|standard|fast> --model=<model>', desc: 'Set a model for a tier' },
       { name: 'free', desc: 'List available free models' },
       { name: 'reset', desc: 'Reset all tier assignments' },
-      { name: 'usage', desc: 'Show token usage per tier' },
-      { name: 'cost', desc: 'Show cost breakdown' },
       { name: 'resolve --json', desc: 'Resolve the model for an embedded workflow given host context' },
     ],
   },

package/lib/config/legacy-config-migration.mjs

@@ -0,0 +1,59 @@
+/**
+ * lib/config/legacy-config-migration.mjs — one-time forward migration of model
+ * tier overrides from the pre-XDG legacy config into the active XDG config.
+ *
+ * The config move to $XDG_CONFIG_HOME/construct (see lib/config/xdg.mjs) is a
+ * clean break with no legacy read, so any install that set CX_MODEL_* before
+ * the move keeps those values stranded in ~/.construct/config.env. Resolution
+ * reads only the XDG path, so doctor then reports "no tier configured" until
+ * the user hand-copies the keys. This mirrors the stranded tier overrides
+ * forward, and never overwrites a value the XDG config already defines.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { parseEnvFile, writeEnvValues } from '../env-config.mjs';
+import { configDir } from './xdg.mjs';
+
+// Only model tier overrides migrate. API keys and other secrets are
+// intentionally out of scope — they are re-established through the credential
+// bootstrap, not copied between paths.
+
+const MIGRATABLE_KEY = /^(?:CX|CONSTRUCT)_MODEL_[A-Z0-9_]+$/;
+
+export function legacyConfigPath(homeDir = os.homedir()) {
+  return path.join(homeDir, '.construct', 'config.env');
+}
+
+/**
+ * Migrate stranded CX_MODEL_ and CONSTRUCT_MODEL_ tier overrides from the
+ * legacy config into the XDG config. Returns the keys that were written so
+ * callers can surface a one-time message and refresh their in-process env.
+ */
+export function migrateLegacyModelConfig({ homeDir = os.homedir(), env = process.env } = {}) {
+  const legacyPath = legacyConfigPath(homeDir);
+  const xdgPath = path.join(configDir(homeDir, env), 'config.env');
+  const result = { performed: false, migrated: {}, legacyPath, xdgPath };
+
+  if (legacyPath === xdgPath || !fs.existsSync(legacyPath)) return result;
+
+  const legacyEnv = parseEnvFile(legacyPath);
+  const xdgEnv = parseEnvFile(xdgPath);
+
+  const migrated = {};
+  for (const [key, value] of Object.entries(legacyEnv)) {
+    if (!MIGRATABLE_KEY.test(key)) continue;
+    if (value === '' || value === undefined) continue;
+    if (xdgEnv[key] !== undefined && xdgEnv[key] !== '') continue;
+    migrated[key] = value;
+  }
+
+  if (Object.keys(migrated).length === 0) return result;
+
+  writeEnvValues(xdgPath, migrated);
+  result.performed = true;
+  result.migrated = migrated;
+  return result;
+}

package/lib/runtime-env.mjs

@@ -1,7 +1,7 @@
 /**
  * lib/runtime-env.mjs — Construct runtime environment with credential bootstrap.
  *
- * prepareConstructEnv merges ~/.construct/config.env into the process environment.
+ * prepareConstructEnv merges ~/.config/construct/config.env into the process environment.
  * Credential auto-link from 1Password runs only when autoLink:true (setup-credentials).
  */