@geraldmaron/construct 1.0.24 → 1.1.1

package/lib/storage/embeddings-engine.mjs

@@ -8,7 +8,10 @@
  *   - local    → ONNX Transformers (Xenova/all-MiniLM-L6-v2, 384d) — DEFAULT
  *   - openai   → OpenAI API (text-embedding-3-small, 1536d)
  *   - ollama   → Ollama server (nomic-embed-text, 768d)
- *   - hashing  → Deterministic bag-of-words (256d) — fallback / test fixture only
+ *   - hashing  → Deterministic bag-of-words (256d) — opt-in via the id only; never
+ *                a silent fallback (256d has no semantics and mismatches the 384d
+ *                vector schema, so an accidental fall-through degrades retrieval
+ *                invisibly). An unknown CONSTRUCT_EMBEDDING_MODEL fails loud.
  *
  * OpenAI policy:
  *   - When CONSTRUCT_EMBEDDING_MODEL=openai and OPENAI_API_KEY is missing,
@@ -28,6 +31,8 @@ const ADAPTERS = {
   hashing: () => import('./embeddings-legacy.mjs'),
 };
 
+const KNOWN_MODELS = new Set(Object.keys(ADAPTERS));
+
 const DEFAULT_MODEL = 'local';
 
 let openaiFallbackWarned = false;
@@ -39,7 +44,16 @@ let openaiFallbackWarned = false;
  */
 function resolveModelId(env) {
   const requested = (env.CONSTRUCT_EMBEDDING_MODEL || DEFAULT_MODEL).toLowerCase();
-  if (requested !== 'openai') return requested;
+  if (requested !== 'openai') {
+    if (!KNOWN_MODELS.has(requested)) {
+      throw new Error(
+        `CONSTRUCT_EMBEDDING_MODEL='${requested}' is not a known embedding model ` +
+        `(${[...KNOWN_MODELS].join('|')}). Fix the value — falling through to the 256d ` +
+        `hashing adapter would silently degrade retrieval and mismatch the vector schema.`
+      );
+    }
+    return requested;
+  }
 
   if (env.OPENAI_API_KEY) return 'openai';
 
@@ -69,7 +83,7 @@ function resolveModelId(env) {
  */
 export async function embedText(text, { env = process.env } = {}) {
   const modelId = resolveModelId(env);
-  const loader = ADAPTERS[modelId] || ADAPTERS.hashing;
+  const loader = ADAPTERS[modelId];
   const { embed } = await loader();
   return embed(text, { env });
 }
@@ -82,7 +96,7 @@ export async function embedText(text, { env = process.env } = {}) {
  */
 export async function embedBatch(texts, { env = process.env } = {}) {
   const modelId = resolveModelId(env);
-  const loader = ADAPTERS[modelId] || ADAPTERS.hashing;
+  const loader = ADAPTERS[modelId];
   const { embedBatch } = await loader();
   return embedBatch(texts, { env });
 }
@@ -94,7 +108,7 @@ export async function embedBatch(texts, { env = process.env } = {}) {
  */
 export async function getEmbeddingModelInfo({ env = process.env } = {}) {
   const modelId = resolveModelId(env);
-  const loader = ADAPTERS[modelId] || ADAPTERS.hashing;
+  const loader = ADAPTERS[modelId];
   const { getModelInfo } = await loader();
   return getModelInfo({ env });
 }

package/lib/storage/embeddings-local.mjs

@@ -1,9 +1,11 @@
 /**
  * lib/storage/embeddings-local.mjs — Local ONNX embedding via @huggingface/transformers.
  *
- * Lazy-loads the model, caches to disk, uses a single-worker queue to avoid
- * parallel inference contention. Falls back to hashing-bow-v1 if the model
- * fails to load.
+ * Lazy-loads the model from local cache only and runs inference offline. Falls
+ * back to hashing-bow-v1 when the model is absent or fails to load. Remote model
+ * fetching is disabled (allowRemoteModels=false): the runtime path never reaches
+ * the network, so a first run with no cached weights degrades to the hashing
+ * backend rather than downloading from the HuggingFace hub.
  *
  * Model: Xenova/all-MiniLM-L6-v2 (384 dimensions, quantized)
  */
@@ -29,6 +31,7 @@ async function getExtractor(cacheDir) {
   modelPromise = (async () => {
     const { pipeline, env: hfEnv } = await import('@huggingface/transformers');
     hfEnv.allowLocalModels = true;
+    hfEnv.allowRemoteModels = false;
     hfEnv.useBrowserCache = false;
     try {
       const ex = await pipeline('feature-extraction', MODEL_ID, {

package/lib/storage/file-lock.mjs

@@ -50,17 +50,24 @@ function tryAcquire(lockPath) {
     return true;
   } catch (err) {
     if (err.code !== 'EEXIST') throw err;
-    let holder = null;
-    try { holder = Number(readFileSync(lockPath, 'utf8').trim()); } catch { /* unreadable */ }
-    if (!isHolderAlive(holder)) {
-      try { unlinkSync(lockPath); } catch { /* race */ }
-      try {
-        writeFileSync(lockPath, String(process.pid), { flag: 'wx' });
-        heldLocks.add(lockPath);
-        return true;
-      } catch { return false; }
-    }
-    return false;
+
+    // Steal only from a holder we can positively read as dead. An empty or
+    // unreadable pidfile is the mid-create window of a live holder, not a
+    // crash; stealing it would admit two writers and break an append chain.
+    // The acquire timeout still bounds the wait if the holder truly crashed.
+
+    let raw = '';
+    try { raw = readFileSync(lockPath, 'utf8').trim(); } catch { return false; }
+    if (raw === '') return false;
+    const holder = Number(raw);
+    if (!Number.isFinite(holder) || isHolderAlive(holder)) return false;
+
+    try { unlinkSync(lockPath); } catch { /* another stealer won */ }
+    try {
+      writeFileSync(lockPath, String(process.pid), { flag: 'wx' });
+      heldLocks.add(lockPath);
+      return true;
+    } catch { return false; }
   }
 }
 

package/lib/telemetry/beads-fallback.mjs

@@ -0,0 +1,40 @@
+/**
+ * lib/telemetry/beads-fallback.mjs — count legacy-lock fallback firings.
+ *
+ * The beads write path is optimistic by default; the exclusive file-lock runs only
+ * as the PATH-3 fallback after optimistic retries exhaust. Whether that fallback
+ * ever fires in practice is the evidence that decides if the lock + wait-queue can
+ * be retired (bead construct-nhn5): one JSON line per firing to
+ * ~/.cx/beads-fallback.jsonl. Zero entries over a representative window = safe to
+ * remove; entries name the bd commands that actually contend.
+ *
+ * Errors here are non-fatal — telemetry must never add a failure mode to the
+ * fallback it observes.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { appendBounded } from '../logging/rotate.mjs';
+import { cxDir } from '../paths.mjs';
+
+export function defaultLogPath() {
+  return path.join(cxDir(), 'beads-fallback.jsonl');
+}
+
+export function logBeadsFallback(event, opts = {}) {
+  const logPath = opts.logPath || defaultLogPath();
+  const entry = {
+    ts: new Date().toISOString(),
+    command: event?.command || 'unknown',
+  };
+  try {
+    fs.mkdirSync(path.dirname(logPath), { recursive: true });
+    appendBounded('beads-fallback', logPath, JSON.stringify(entry) + '\n');
+  } catch { /* best-effort */ }
+}
+
+export function readBeadsFallbacks({ logPath = defaultLogPath() } = {}) {
+  if (!fs.existsSync(logPath)) return [];
+  return fs.readFileSync(logPath, 'utf8').split('\n').filter(Boolean).map((l) => {
+    try { return JSON.parse(l); } catch { return null; }
+  }).filter(Boolean);
+}

package/lib/telemetry/hook-calls.mjs

@@ -0,0 +1,138 @@
+/**
+ * lib/telemetry/hook-calls.mjs — measure which hooks fire and which actually block.
+ *
+ * Hooks carry @p95ms latency budgets but no record of how often each one fires or
+ * blocks, so a hook that gates real mistakes and one that has never fired once look
+ * identical. The central dispatcher (`construct hook <name>`) appends one JSON line
+ * per invocation to ~/.cx/hook-calls.jsonl with the hook id, the outcome derived
+ * from its exit code, and latency, so `construct hooks:usage` can answer which hooks
+ * earn their keep before any are consolidated.
+ *
+ * Outcome is what the dispatcher can observe centrally: exit 0 = ok, exit 2 = blocked
+ * (the Claude Code convention for a refused tool call — see block-no-verify), any
+ * other non-zero = error. A hook that mutates state without blocking reads as `ok`
+ * here; per-hook mutation reporting is a separate, opt-in signal.
+ *
+ * Disable with CONSTRUCT_HOOK_TELEMETRY=off. Errors here are non-fatal — telemetry
+ * must never change a hook's exit code or add a failure mode to the hot path.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { appendBounded } from '../logging/rotate.mjs';
+import { resolveProjectScope } from '../project-root.mjs';
+import { cxDir } from '../paths.mjs';
+
+// cxDir() (not os.homedir()) so CX_HOME_OVERRIDE isolates the log in tests and the
+// path stays consistent with the rest of ~/.cx. Resolved per-call so an override
+// set after import still takes effect.
+
+export function defaultLogPath() {
+  return path.join(cxDir(), 'hook-calls.jsonl');
+}
+
+// Exit-code → outcome, using the Claude Code hook convention (2 = block a tool
+// call). Anything else non-zero is a hook that errored rather than deliberately
+// gated, which is itself a value signal (a hook erroring every fire is noise).
+
+export function outcomeFromExit(code) {
+  if (code === 0 || code == null) return 'ok';
+  if (code === 2) return 'blocked';
+  return 'error';
+}
+
+/**
+ * Fire-and-forget log of one hook invocation.
+ *
+ * @param {object} event
+ * @param {string} event.hookId — the hook name, e.g. "block-no-verify"
+ * @param {number} [event.exitCode] — the hook's process exit code
+ * @param {'ok'|'blocked'|'error'} [event.outcome] — derived from exitCode if omitted
+ * @param {number} [event.latencyMs]
+ * @param {object} [opts]
+ * @param {string} [opts.logPath]
+ * @param {NodeJS.ProcessEnv} [opts.env]
+ */
+export function logHookCall(event, opts = {}) {
+  const env = opts.env || process.env;
+  if (env.CONSTRUCT_HOOK_TELEMETRY === 'off') return;
+  if (!event || !event.hookId) return;
+
+  const logPath = opts.logPath || defaultLogPath();
+  const outcome = event.outcome || outcomeFromExit(event.exitCode);
+  const scope = resolveProjectScope();
+  const entry = {
+    ts: new Date().toISOString(),
+    hookId: event.hookId,
+    outcome,
+    ...(event.exitCode != null ? { exitCode: event.exitCode } : {}),
+    ...(scope?.projectId ? { projectId: scope.projectId } : {}),
+    ...(event.latencyMs != null ? { latencyMs: event.latencyMs } : {}),
+  };
+
+  try {
+    fs.mkdirSync(path.dirname(logPath), { recursive: true });
+    appendBounded('hook-calls', logPath, JSON.stringify(entry) + '\n');
+  } catch {
+    // Append-only telemetry; an unwritable home dir is a silent skip rather than
+    // a new failure mode on the hook that triggered the call.
+  }
+}
+
+/**
+ * Roll a hook-calls log up into per-hook stats: fire count, blocked/error counts,
+ * most-recent timestamp, latency percentiles. A hook with calls but zero blocks/
+ * errors over a long window is a pure observer — a demotion candidate.
+ */
+export function summarizeHookCalls({ logPath = defaultLogPath(), since } = {}) {
+  if (!fs.existsSync(logPath)) return { totalEvents: 0, hooks: {} };
+  const lines = fs.readFileSync(logPath, 'utf8').split('\n').filter(Boolean);
+  const sinceTs = since ? _parseSince(since) : null;
+  const hooks = {};
+  for (const line of lines) {
+    let entry;
+    try { entry = JSON.parse(line); } catch { continue; }
+    if (!entry?.hookId) continue;
+    if (sinceTs && entry.ts && entry.ts < sinceTs) continue;
+    const slot = hooks[entry.hookId] ||= { calls: 0, blocked: 0, errors: 0, latencies: [], lastCalledAt: null };
+    slot.calls += 1;
+    if (entry.outcome === 'blocked') slot.blocked += 1;
+    if (entry.outcome === 'error') slot.errors += 1;
+    if (entry.latencyMs != null) slot.latencies.push(entry.latencyMs);
+    if (entry.ts && (!slot.lastCalledAt || entry.ts > slot.lastCalledAt)) slot.lastCalledAt = entry.ts;
+  }
+  const result = {};
+  for (const [id, slot] of Object.entries(hooks)) {
+    result[id] = {
+      calls: slot.calls,
+      blocked: slot.blocked,
+      errors: slot.errors,
+      lastCalledAt: slot.lastCalledAt,
+      ...(slot.latencies.length ? _latencyStats(slot.latencies) : {}),
+    };
+  }
+  return { totalEvents: lines.length, hooks: result };
+}
+
+/**
+ * Hooks with zero fire events in the window — they cost a settings entry and a
+ * spawn budget but have never run, so they are consolidation candidates.
+ */
+export function findIdleHooks({ logPath = defaultLogPath(), since = '30d', allHookIds = [] } = {}) {
+  const { hooks } = summarizeHookCalls({ logPath, since });
+  const active = new Set(Object.keys(hooks));
+  return allHookIds.filter((id) => !active.has(id));
+}
+
+function _parseSince(since) {
+  const m = String(since).match(/^(\d+)(d|h|m)$/);
+  if (!m) return null;
+  const ms = parseInt(m[1], 10) * ({ d: 86400000, h: 3600000, m: 60000 }[m[2]]);
+  return new Date(Date.now() - ms).toISOString();
+}
+
+function _latencyStats(arr) {
+  const sorted = [...arr].sort((a, b) => a - b);
+  const p = (pct) => sorted[Math.floor((pct / 100) * (sorted.length - 1))];
+  return { p50LatencyMs: p(50), p95LatencyMs: p(95) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geraldmaron/construct",
-  "version": "1.0.24",
+  "version": "1.1.1",
   "type": "module",
   "packageManager": "npm@11.5.1",
   "description": "Construct — agent orchestration layer for OpenCode, Claude Code, and other coding surfaces",
@@ -92,7 +92,9 @@
     "@opentelemetry/exporter-trace-otlp-http": "^0.218.0",
     "@opentelemetry/resources": "^2.7.1",
     "@opentelemetry/sdk-trace-node": "^1.25.0",
-    "@opentelemetry/semantic-conventions": "^1.25.0"
+    "@opentelemetry/semantic-conventions": "^1.25.0",
+    "mammoth": "^1.12.0",
+    "unpdf": "^1.6.2"
   },
   "overrides": {
     "express-rate-limit": "8.5.1"

package/personas/construct.md

@@ -6,7 +6,7 @@ You are Construct. The user talks only to you; internal routing and specialist d
 
 **Anti-fabrication contract**: every load-bearing claim cites a verifiable source. Missing source becomes `unknown` or `[unverified]`. Specialists tailor; the persona never weakens. See `rules/common/no-fabrication.md`.
 
-## Start of every session
+## Start of every session <!-- cx:prio=3 -->
 
 Before responding, run in parallel. do not narrate:
 1. `project_context`. state from `.cx/context.md`
@@ -23,7 +23,7 @@ Honor the project operating hierarchy:
 
 Use the single-writer rule whenever multiple sessions are active: if two sessions would touch the same file, one session owns the edit and the other reviews, researches, or waits for handoff.
 
-## Classify before acting
+## Classify before acting <!-- cx:prio=1 -->
 
 Before any non-trivial request, CALL the code-backed orchestration policy via the `orchestration_policy` MCP tool with the request text and your `fileCount` / `moduleCount` / `introducesContract` estimate. Do not classify from memory. Honor the returned `track` and `specialists`. When `track` is `orchestrated` you may not author the deliverable yourself: emit the task-packet, dispatch the chain, return in Construct's voice after verdicts. Visual deliverables (wireframes, diagrams, decks) use real visual tools, not bullet prose.
 
@@ -31,7 +31,7 @@ Tracks: immediate (act directly), focused (one bounded specialist), orchestrated
 
 Orchestrated dispatches emit a task-packet with `goal`, `intent`, `workCategory`, `riskFlags`, `acceptanceCriteria` before naming specialists (`specialists/contracts.json:construct-to-orchestrator`).
 
-## Gates and contracts (org-in-a-box)
+## Gates and contracts (org-in-a-box) <!-- cx:prio=2 -->
 
 `orchestration_policy` returns three artifacts; honor all three:
 
@@ -41,16 +41,16 @@ Orchestrated dispatches emit a task-packet with `goal`, `intent`, `workCategory`
 
 Before DONE: postconditions met · sources cited · framing logged · ADRs have Rejected alternatives.
 
-## Branch + commit approval
+## Branch + commit approval <!-- cx:prio=1 -->
 
 - **Working branch is surfaced every session** at the top of session-start. Restate it before any mutating operation.
 - **Never commit, push, or merge without asking first.** Before `git commit`, `git push`, or `gh pr merge`: state branch, show the proposed message / refspec / PR number verbatim, wait for explicit yes. A batch go-ahead covers a defined sequence; new commits later are their own gate. See `rules/common/commit-approval.md`.
 
-## Intake surface
+## Intake surface <!-- cx:prio=3 -->
 
 The active profile (`construct profile show`) sets the intake taxonomy. Session-start surfaces pending intake at `.cx/intake/pending/<id>.json`. Read with `construct intake show <id>`; the triage block names the primary owner, recommended chain, and next action. For non-trivial signals, plan with `construct graph from-intake <id>` and update node status with evidence (`construct graph status … done --evidence=…`). A node cannot reach `done` without an evidence record. Team / enterprise mode wraps tool calls in the MCP broker; when it returns `ApprovalRequired`, surface the question and never bypass.
 
-## Action discipline
+## Action discipline <!-- cx:prio=1 -->
 
 - Dispatch, don't solo-plan: 3+ files, 2+ modules, or a new contract → cx-architect owns the plan.
 - Ask or look up, don't speculate: call `context7_query-docs` / `WebFetch`, ask, or commit to a default. Never a fourth round of internal debate.
@@ -58,11 +58,11 @@ The active profile (`construct profile show`) sets the intake taxonomy. Session-
 - Probe before bulk read: check size via `Glob` / `wc -l` or a `limit: 50` probe before `Read` with `limit > 200`.
 - Start-of-task: parallel bootstrap (above) + `cx_trace` before anything mutating.
 
-## Communication + state
+## Communication + state <!-- cx:prio=2 -->
 
 Lead with the answer. One question when blocked. Confirm what changed when done.
 
-**Output style**: format human-facing output (terminal, prose, dashboard) for neurodivergent readers — answer first, clear hierarchy, scannable chunks, plain language, explicit next step; never rely on color or motion alone; honor `NO_COLOR` and reduced-motion. Presentation only — never reshape machine-readable output (`--json`, parsed tokens, registries, contracts). See `rules/common/neurodivergent-output.md`.
+**Output style**: format human-facing output (terminal, prose, dashboard) for neurodivergent readers — answer first, clear hierarchy, plain language, explicit next step. Prose for reasoning; lists only for genuinely parallel items where scanning helps, never a wall of bullets. Never rely on color or motion alone; honor `NO_COLOR` and reduced-motion. Presentation only — never reshape machine-readable output (`--json`, parsed tokens, registries, contracts). See `rules/common/neurodivergent-output.md`.
 
 **Tool invisibility**: deliverables are about the user's project, never Construct. Never name Construct, `cx-*` role ids, or internal orchestration mechanics in artifact content unless the subject project is Construct itself. Provenance goes in a comment, not the prose. See `rules/common/tool-invisibility.md`.
 
@@ -70,7 +70,7 @@ Non-trivial work: update Beads (`bd note <id>`), `plan.md`, docs with owner / ac
 
 Load-bearing state: `AGENTS.md`, `.cx/context.md`/`.json`, `docs/README.md`, `docs/architecture.md` (read at session start, update before DONE, prune stale sections). `plan.md` is local-only.
 
-## Quality gates
+## Quality gates <!-- cx:prio=2 -->
 
 After any implementation, dispatch validation before marking done:
 1. cx-reviewer. correctness, regression, coverage
@@ -79,17 +79,17 @@ After any implementation, dispatch validation before marking done:
 
 Do not mark `done` until cx-reviewer and cx-qa return verdicts. BLOCKED or any CRITICAL finding stops shipping.
 
-## Hard release gates
+## Hard release gates <!-- cx:prio=3 -->
 
 Run `npm run release:check` before any commit or push. never wait for CI. Commits follow `.gitmessage`; PRs follow `.github/pull_request_template.md`. Full policy: `rules/common/release-gates.md`.
 
-## Loop guard
+## Loop guard <!-- cx:prio=1 -->
 
 Same action 3+ times with no state change → stop. Report what was tried, what blocked progress, what decision is needed.
 
 Before stopping: surface incomplete tracker-linked plan slices and unmet acceptance criteria. Do not stop silently with work in-flight.
 
-## Drive mode
+## Drive mode <!-- cx:prio=3 -->
 
 Activates on word-boundary triggers. `/work:drive`, standalone `drive`, or `full send`. Substring matches do not count.
 

package/platforms/capabilities.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "../schemas/platform-capabilities.schema.json",
+  "version": 1,
+  "hosts": {
+    "claude": {
+      "displayName": "Claude Code",
+      "hasNativeSubagents": false,
+      "instructionsOnly": false,
+      "supportsMcp": true,
+      "configFormat": "json",
+      "localModelProvisioning": "none",
+      "hooks": {
+        "supported": true,
+        "globalAllowlist": [
+          "pre:bash:block-no-verify",
+          "pre:bash:guard-dangerous",
+          "pre:edit:config-protection",
+          "pre:edit-guard",
+          "post:edit:json-validate",
+          "post:edit:scan-secrets"
+        ]
+      },
+      "globalMcpAllowlist": ["context7"]
+    },
+    "codex": {
+      "displayName": "Codex",
+      "hasNativeSubagents": false,
+      "instructionsOnly": false,
+      "supportsMcp": true,
+      "configFormat": "toml",
+      "localModelProvisioning": "none",
+      "hooks": { "supported": false, "globalAllowlist": [] },
+      "globalMcpAllowlist": []
+    },
+    "copilot": {
+      "displayName": "Copilot",
+      "hasNativeSubagents": false,
+      "instructionsOnly": true,
+      "supportsMcp": false,
+      "configFormat": "markdown",
+      "localModelProvisioning": "none",
+      "hooks": { "supported": false, "globalAllowlist": [] },
+      "globalMcpAllowlist": []
+    },
+    "opencode": {
+      "displayName": "OpenCode",
+      "hasNativeSubagents": true,
+      "instructionsOnly": false,
+      "supportsMcp": true,
+      "configFormat": "json",
+      "localModelProvisioning": "modelfile",
+      "hooks": { "supported": false, "globalAllowlist": [] },
+      "globalMcpAllowlist": []
+    },
+    "vscode": {
+      "displayName": "VS Code",
+      "hasNativeSubagents": true,
+      "instructionsOnly": false,
+      "supportsMcp": true,
+      "configFormat": "json",
+      "localModelProvisioning": "none",
+      "hooks": { "supported": false, "globalAllowlist": [] },
+      "globalMcpAllowlist": []
+    },
+    "cursor": {
+      "displayName": "Cursor",
+      "hasNativeSubagents": true,
+      "instructionsOnly": false,
+      "supportsMcp": true,
+      "configFormat": "json",
+      "localModelProvisioning": "none",
+      "hooks": { "supported": false, "globalAllowlist": [] },
+      "globalMcpAllowlist": []
+    }
+  }
+}

package/platforms/opencode/sync-config.mjs

@@ -1,13 +1,51 @@
 #!/usr/bin/env node
 /**
- * sync-config.mjs — Fetch free models from OpenRouter and sync into OpenCode config.
- * Run periodically or during install to keep the free model list current.
+ * sync-config.mjs — Fetch free models from OpenRouter and local models from Ollama,
+ * and sync into OpenCode config.
  */
 import fs from "node:fs";
-import { readOpenCodeConfig, writeOpenCodeConfig, findOpenCodeConfigPath } from "../lib/opencode-config.mjs";
+import { spawnSync } from "node:child_process";
+import { readOpenCodeConfig, writeOpenCodeConfig, findOpenCodeConfigPath } from "../../lib/opencode-config.mjs";
+import { ensureLocalContextVariants, modelDigest } from "../../lib/ollama/provision-context.mjs";
+import { isKnownCollapsed } from "../../lib/ollama/capability-store.mjs";
+
+const LOCAL_NUM_CTX = Number(process.env.CONSTRUCT_LOCAL_NUM_CTX) || 32768;
 
 const configPath = findOpenCodeConfigPath();
 
+async function fetchLocalOllamaModels() {
+  try {
+    const r = spawnSync("ollama", ["list"], { encoding: "utf8" });
+    if (r.status !== 0) return [];
+    
+    const lines = r.stdout.trim().split("\n").slice(1);
+    const models = lines.map(line => {
+      const parts = line.split(/\s+/).filter(Boolean);
+      const id = parts[0];
+      const size = parts[2];
+      return { id, name: id, size };
+    });
+
+    // Identify redundant tags (same family, many tags)
+    const familyMap = new Map();
+    for (const m of models) {
+      const family = m.id.split(":")[0];
+      if (!familyMap.has(family)) familyMap.set(family, []);
+      familyMap.get(family).push(m);
+    }
+
+    for (const [family, tags] of familyMap) {
+      if (tags.length > 2) {
+        console.log(`[cleanup] Potential redundant tags for ${family}: ${tags.map(t => t.id).join(", ")}`);
+      }
+    }
+
+    return models;
+  } catch {
+    return [];
+  }
+}
+
 async function fetchFreeModels() {
   try {
     const res = await fetch("https://openrouter.ai/api/v1/models");
@@ -31,39 +69,97 @@ async function main() {
 
   const { config } = readOpenCodeConfig();
   const freeModels = await fetchFreeModels();
+  const localModels = await fetchLocalOllamaModels();
 
-  if (freeModels.length === 0) {
-    console.log("No free models fetched. Config unchanged.");
+  if (freeModels.length === 0 && localModels.length === 0) {
+    console.log("No models fetched. Config unchanged.");
     return;
   }
 
   if (!config.provider) config.provider = {};
-  if (!config.provider.openrouter) {
-    config.provider.openrouter = {
-      npm: "@ai-sdk/openai-compatible",
-      name: "OpenRouter",
-      options: {
-        baseURL: "https://openrouter.ai/api/v1",
-        headers: {}
-      },
-      models: {}
-    };
+  
+  // Sync OpenRouter Free Models
+  if (freeModels.length > 0) {
+    if (!config.provider.openrouter) {
+      config.provider.openrouter = {
+        npm: "@ai-sdk/openai-compatible",
+        name: "OpenRouter",
+        options: {
+          baseURL: "https://openrouter.ai/api/v1",
+          headers: {}
+        },
+        models: {}
+      };
+    }
+    const existingOR = config.provider.openrouter.models ?? {};
+    for (const model of freeModels) {
+      const cleanName = model.name.replace(/\s*\(free\)/gi, "").trim();
+      existingOR[model.id] = { name: `[free] ${cleanName}` };
+    }
+    config.provider.openrouter.models = Object.fromEntries(
+      Object.entries(existingOR).sort((a, b) => (a[1].name ?? a[0]).localeCompare(b[1].name ?? b[0]))
+    );
   }
 
-  const existingModels = config.provider.openrouter.models ?? {};
-  const merged = { ...existingModels };
-  for (const model of freeModels) {
-    if (!merged[model.id]) {
-      merged[model.id] = { name: `${model.name} (free)` };
+  // Sync Local Ollama Models
+  if (localModels.length > 0) {
+    if (!config.provider.ollama) {
+      config.provider.ollama = {
+        npm: "@ai-sdk/openai-compatible",
+        name: "Ollama",
+        options: {
+          baseURL: "http://localhost:11434/v1"
+        },
+        models: {}
+      };
     }
-  }
+    // A raw model runs at Ollama's 4096 default over the /v1 path, which a Construct
+    // session's tool schemas overrun. Provision a context-extended Modelfile variant
+    // for each tool-capable model lacking a baked num_ctx (any size — capability does
+    // not track size) and register the variant in place of the raw tag so the model
+    // OpenCode actually talks to has a real context window.
+
+    const { mapping: variantMap, actions } = ensureLocalContextVariants({ numCtx: LOCAL_NUM_CTX });
+    for (const a of actions) {
+      if (a.action === "created" || a.action === "would-create") console.log(`[ollama] context variant ${a.action}: ${a.variant} (num_ctx ${LOCAL_NUM_CTX})`);
+    }
+
+    const existingLocal = config.provider.ollama.models ?? {};
+    for (const model of localModels) {
+      const registerId = variantMap[model.id] || model.id;
+      // Register the context-extended variant in place of the raw tag so the model
+      // picker surfaces the windowed option, not the one Ollama serves at 4096.
 
-  config.provider.openrouter.models = Object.fromEntries(
-    Object.entries(merged).sort((a, b) => (a[1].name ?? a[0]).localeCompare(b[1].name ?? b[0]))
-  );
+      if (registerId !== model.id) delete existingLocal[model.id];
+      existingLocal[registerId] = {
+        name: registerId.replace(/\s*\(local\)/gi, "").trim(),
+        family: registerId.includes("qwen") ? "qwen2" : "llama",
+        tool_call: true
+      };
+
+      // Capability honesty: a model the probe recorded as COLLAPSED (digest still
+      // matching) word-salads on the agentic loop. Warn rather than hide — the
+      // user keeps the choice and can re-probe — so a stale or false verdict never
+      // silently strands a working model.
+      if (isKnownCollapsed(model.id, modelDigest(model.id))) {
+        console.log(`[ollama] WARNING: ${model.id} probed COLLAPSED — not agentic-capable. Re-probe: construct doctor --probe-local`);
+      }
+    }
+    config.provider.ollama.models = Object.fromEntries(
+      Object.entries(existingLocal).sort((a, b) => (a[1].name ?? a[0]).localeCompare(b[1].name ?? b[0]))
+    );
+
+    // Agentic coherence is model-specific and not predictable from size: some small
+    // coder models collapse into repetition on an agentic system prompt while others
+    // run the same Construct payload cleanly. Surface the empirical probe rather than
+    // silently registering a model that will produce word salad.
+
+    console.log("[ollama] Verify a model handles agentic prompts before relying on it:");
+    console.log("[ollama]   node lib/ollama/provision-context.mjs --probe --model=<id>");
+  }
 
   writeOpenCodeConfig(config, configPath);
-  console.log(`Synced ${freeModels.length} free models from OpenRouter.`);
+  console.log(`Synced ${freeModels.length} free models and ${localModels.length} local models.`);
 }
 
 main();