@lawaty/lacode 0.4.0 → 0.4.2

package/dist/index.js

@@ -30,6 +30,7 @@ var ORPHAN_TMP_MS = 60 * 1e3;
 var CATALOG_TTL_MS = 10 * 60 * 1e3;
 var STUCK_MIN_AGE_MS = 5 * 60 * 1e3;
 var STUCK_IDLE_MS = 3 * 60 * 1e3;
+var MAX_CLAIM_AGE_MS = 30 * 60 * 1e3;
 var HANG_COOLDOWN_MS = 10 * 60 * 1e3;
 var UNAVAILABLE_COOLDOWN_MS = 60 * 1e3;
 var MAX_WEIGHT = 100;
@@ -203,6 +204,8 @@ var LIMIT_PATTERNS = [
 ];
 var isLimitText = (text) => LIMIT_PATTERNS.some((re) => re.test(text));
 var isUnavailableText = (text) => UNAVAILABLE_PATTERN.test(text);
+var TRANSIENT_GATEWAY_PATTERNS = [/queue budget/i, /exceeded queue/i, /aborted due to timeout/i, /timeout/i];
+var isTransientGatewayText = (text) => TRANSIENT_GATEWAY_PATTERNS.some((re) => re.test(text));
 var statedCooldown = (text) => {
   const hm = /resets?\s+in\s+(\d+)\s*(?:h|hr|hour)s?\s*(\d+)?\s*(?:m|min|minute)?s?/i.exec(text);
   if (hm) return (Number(hm[1]) * 60 + (hm[2] ? Number(hm[2]) : 0)) * 60 * 1e3;
@@ -291,7 +294,7 @@ function publish(s) {
   if (!s.dirReady) return;
   const now = Date.now();
   const payload = {};
-  for (const [key, claim] of s.own) if (now - claim.t <= CLAIM_TTL_MS) payload[key] = claim;
+  for (const [key, claim] of s.own) if (now - (claim.hb ?? claim.t) <= CLAIM_TTL_MS) payload[key] = claim;
   try {
     writeFileSync(join2(s.dir, `${selfFile(s.id)}.tmp`), JSON.stringify(payload));
     renameSync(join2(s.dir, `${selfFile(s.id)}.tmp`), join2(s.dir, selfFile(s.id)));
@@ -510,6 +513,11 @@ function pickSlot(s, snap, options) {
 function agentFor(base, slot) {
   return `${base}-${slot}`;
 }
+function manualVariant(name) {
+  const direct = /^(.*)-([1-9][0-9]*)$/.exec(name);
+  if (!direct) return void 0;
+  return BASES.includes(direct[1]) ? direct[1] : void 0;
+}
 function acquire(s, base, slot, ownerSession, key, target) {
   const now = Date.now();
   s.own.set(key, { v: base, k: slot.index, m: slot.model, t: now, hb: now, s: ownerSession, g: target });
@@ -567,12 +575,17 @@ function idleFor(s, claim, now) {
   const seen = s.activity.get(target);
   return seen ? now - seen : Infinity;
 }
+function condemnReason(s, claim, now = Date.now()) {
+  const age = now - claim.t;
+  if (age > MAX_CLAIM_AGE_MS) return "overran";
+  if (age > STUCK_MIN_AGE_MS && idleFor(s, claim, now) >= STUCK_IDLE_MS) return "hung";
+  return void 0;
+}
 function findStuck(s, now = Date.now()) {
   const stuck = [];
   for (const [key, claim] of s.own) {
-    if (now - claim.t <= STUCK_MIN_AGE_MS) continue;
-    if (idleFor(s, claim, now) < STUCK_IDLE_MS) continue;
-    stuck.push({ key, claim });
+    const reason = condemnReason(s, claim, now);
+    if (reason) stuck.push({ key, claim, reason });
   }
   return stuck;
 }
@@ -626,15 +639,9 @@ Every question of the form "what does this file do", "where is X handled", or
   that proves it. Never one whole refactor handed over in a single piece \u2014
   see \`# Task size\` below.
 
-The agents you spawn are the pooled \`explore\` / \`implement\` / \`context\`
-bases. **Always spawn the BARE base name and let the plugin choose the slot;
-never name a \`-N\` variant** (\`explore-1\`..\`explore-4\`, \`implement-1\`..,
-\`context-1\`..). The plugin owns which model every pooled spawn runs on: it
-picks the next slot from the pool's weights, current load and cooldowns, and
-rewrites your spawn to that variant for you. Naming a variant bypasses that
-decision, defeats failover, and can pin work to a cooling or unhealthy model.
-If you catch yourself choosing a slot number, you are doing the plugin's job \u2014
-spawn \`explore\` and let it decide.
+Spawn the BARE pooled base \u2014 \`explore\`, \`implement\` or \`context\`. The pool
+refuses a \`-N\` variant, and a refusal means spawn the bare base, never a
+different number.
 
 # When the pool is unavailable
 
@@ -754,10 +761,8 @@ When you need to understand the codebase:
 2. Invoke @explore with specific, focused instructions (e.g. "read src/auth.ts", "grep for 'migration' in *.py files", "list the src/ directory")
 3. @explore will return its findings \u2014 you process them and plan accordingly
 
-Always spawn the BARE pooled base (\`explore\`, \`implement\`, \`context\`) and let
-the plugin choose the slot. Never name a \`-N\` variant (\`explore-1\`..\`explore-4\`);
-doing so bypasses the pool's weights, load and cooldowns, which is the one thing
-the plugin exists to decide.
+Spawn the BARE pooled base (\`explore\`, \`implement\`, \`context\`); the pool
+refuses \`-N\` variants, and a refusal means spawn the bare base, not another number.
 
 If the pool cannot serve a spawn \u2014 every slot cooling or exhausted, or repeated
 failures \u2014 do NOT fall back to reading or planning from your own inspection.
@@ -1015,6 +1020,30 @@ You own exactly these five files and nothing else:
   during work that are not already recorded in the project's own decision
   log. Concise; variable length.
 
+A sixth file sits in the same directory and is not yours:
+\`.opencode/context/manager.md\`. It is the client's own statement of intent
+\u2014 what is being worked on, what comes next, what they have settled, and
+what every agent should keep in mind. It deliberately says nothing about
+where code lives: your five files and the source itself are the only
+authority on that, and this file never contradicts them. It has no fixed
+schema \u2014 read the whole file, because every heading in it is direction.
+
+You never create, edit, rename, or delete it \u2014 not at bootstrap, not in an
+update, not in a review, and not when a run of your own concludes the work
+has moved on. The client edits it, or asks a live agent to edit it on
+their explicit instruction. Either way it is their hand, never yours.
+
+Read it before you write anything. Its \`## Current\` and \`## Next\`
+sections tell you what is actually being worked on, and \`## Confirmed\`
+tells you which of your facts the client has ratified. A fact you are
+writing that appears under \`## Confirmed\` may be stated plainly, without
+a confidence marker; anything else follows your normal rules \u2014 infer
+carefully, mark uncertainty. Never copy its content into the five files.
+
+A missing or empty section is not an instruction. It means the client has
+not said, not that you may assume anything \u2014 proceed exactly as you would
+without the file.
+
 Never create, modify, or delete anything outside \`.opencode/context/\`. The
 \`edit\` permission enforces this. Do not attempt to work around it with bash.
 
@@ -1049,6 +1078,11 @@ Then write the five files. For each significant subsystem, give a short
 reason. This is the single most valuable thing you produce: where an agent
 should open its editor next.
 
+manager.md is created for the client by the plugin, not by you; if it is
+missing anyway, mention once in your final report that they can add it
+themselves to record what is being worked on, what comes next, and what
+they have ratified. Never create it.
+
 # Incremental update
 
 Trigger: \`.opencode/context/\` exists and work has just been done here.
@@ -1076,6 +1110,14 @@ that is already stated in another context file \u2014 one fact has one home, and
 the other files link to it. If nothing material changed, make no edits and
 report "no update needed".
 
+Before editing, re-read manager.md: its \`## Current\` and \`## Next\`
+sections tell you what the client is actually working on, and its
+\`## Confirmed\` section settles which of your facts are ratified. If what
+you are about to write would place the code somewhere the client never
+described, trust the code, make the edit the code justifies, and report
+the gap in your final message \u2014 never reconcile the two sides silently,
+and never edit manager.md to close it.
+
 # Minimal exploration
 
 Default shape:
@@ -1170,9 +1212,14 @@ Audit the five files for:
 - duplicated information \u2014 one canonical place per fact
 - missing canonical entry points for significant subsystems
 - unsupported assumptions \u2014 anything unmarked that you cannot verify
+- manager.md, if present: is \`## Current\` and \`## Next\` still true of
+  recent work, is every \`## Confirmed\` entry still true of the code, has
+  it outgrown roughly 150 lines \u2014 report findings, but never edit, prune,
+  or reorganize it; that is the client's call
 
-Fix problems only in \`.opencode/context/\`. Never modify source code during a
-review. Report what you found, what you fixed, and what you could not verify.
+Fix problems only in the five files you own \u2014 never in manager.md, which
+belongs to the client. Never modify source code during a review. Report
+what you found, what you fixed, and what you could not verify.
 
 # Reporting
 
@@ -1190,7 +1237,9 @@ Finish with a short report:
       "edit": {
         "*": "deny",
         "*/.opencode/context/**": "allow",
-        ".opencode/context/**": "allow"
+        ".opencode/context/**": "allow",
+        "*/.opencode/context/manager.md": "deny",
+        ".opencode/context/manager.md": "deny"
       },
       "bash": {
         "*": "deny",
@@ -1292,7 +1341,13 @@ Remember: write conclusions, not inventories. Link to the project's existing
 documentation instead of duplicating it.
 
 Report what you created or updated, what you deliberately left out, and
-anything that contradicts the code or existing docs.`
+anything that contradicts the code or existing docs.
+
+If \`.opencode/context/manager.md\` does not exist, mention in your final
+report that the client can add it themselves \u2014 their own file with
+\`## Current\`, \`## Next\`, \`## Confirmed\` and \`## Instructions\` \u2014 for what
+is being worked on, what comes next, what they have ratified, and standing
+direction. Never create it.`
   },
   "context-update": {
     description: "Incrementally update .opencode/context/ after recent work via the context agent.",
@@ -1323,8 +1378,9 @@ timestamp-only edits. If nothing material changed, make no edits and report
     subtask: true,
     template: `Context review.
 
-Everything outside \`.opencode/context/\` is read-only for this run. Do not
-modify source code under any circumstances.
+Everything outside the five context files is read-only for this run \u2014
+including \`manager.md\`, which belongs to the client. Do not modify source
+code under any circumstances.
 
 Audit the five context files for:
 
@@ -1337,6 +1393,9 @@ Audit the five context files for:
 - missing canonical entry points for significant subsystems
 - unsupported assumptions \u2014 anything stated as fact that you cannot verify,
   or that lacks a confidence marker
+- \`manager.md\`, if present: is \`## Current\` and \`## Next\` still true of
+  recent work, is every \`## Confirmed\` entry still true of the code, has it
+  outgrown roughly 150 lines \u2014 report findings, but never edit it
 
 Fix what you find in \`.opencode/context/\` only, then report: findings, fixes,
 and anything you could not verify.`
@@ -1367,7 +1426,8 @@ Print one PASS/FAIL line per check below, with the exact fix for any FAIL.
    trap: an id that is a valid gateway route but is NOT in the plugin's
    \`omniroute.models\` allowlist fails with
    \`ProviderModelNotFoundError: Model not found\`; the fix is to add that id to
-   the \`models\` array, or use the always-registered \`auto\`.
+   the \`models\` array, or set it as \`combo\` \u2014 the combo id is registered
+   whether or not the gateway advertises it, so it needs no allowlist entry.
 
 Change nothing. Print a final one-line summary of failures.`
   }
@@ -1386,22 +1446,43 @@ function applyCommands(cfg, commands = COMMANDS) {
   }
   return { added, kept };
 }
+var INSTRUCTION_MARKER = "<!-- lacode:context-map-instruction:v1 -->";
+var INSTRUCTION_OPT_OUT = "<!-- lacode:context-map-instruction:off -->";
 var STANDING_INSTRUCTION = `## Repository context map
 
 This project may keep a navigation map in \`.opencode/context/\`. Before broad
 exploration, check whether it exists (\`ls .opencode/context\` \u2014 never the \`glob\`
-tool, which skips hidden directories). If it does, read only the file relevant to
-the task \u2014 architecture.md, contexts.md, conventions.md, workflows.md,
-decisions.md \u2014 then start from the canonical entry points it lists.
-
-Source code is authoritative: if the map disagrees with the code, trust the code,
-say so, and never edit source to match the map. Never edit \`.opencode/context/\`
-yourself \u2014 the context agent owns it. Say in your final report if your
-work revealed something that belongs in the map.`;
+tool, which skips hidden directories). If \`manager.md\` exists there, read it
+first: it is the client's own statement of intent \u2014 what is being worked on,
+what comes next, \`## Confirmed\` lists what the client has ratified, and
+\`## Instructions\` holds standing managerial directions. It outranks every
+other context file and every inference of yours about what matters right now.
+It says nothing about where code lives, so it cannot contradict the code;
+treat its \`## Confirmed\` entries as settled decisions, not as a licence to
+skip reading the code. Any heading in it is direction, so read the whole
+file rather than only the sections above. The rest of the map remains usable,
+just unratified where \`## Confirmed\` does not cover it. Then read only the
+file relevant to the task \u2014 \`architecture.md\`, \`contexts.md\`,
+\`conventions.md\`, \`workflows.md\`, \`decisions.md\` \u2014 and start from the
+canonical entry points it lists.
+
+Source code is authoritative: if the map disagrees with the code,
+trust the code and say so; never edit source to match it.
+Never edit the five context files yourself \u2014 the context agent owns them.
+\`manager.md\` is the client's own file and the context agent is explicitly
+permission-denied from writing it. You may write it only when the client
+explicitly asks you to in this conversation, and then only what they asked
+for; never on your own initiative, and never to "keep it up to date". Say in
+your final report if your work revealed something that belongs to the map, or
+if \`manager.md\` and the code disagree.`;
 function applyInstructions(cfg) {
-  const existing = cfg.instructions;
-  if (Array.isArray(existing) && existing.length > 0) return { added: false };
-  cfg.instructions = [STANDING_INSTRUCTION];
+  const existing = Array.isArray(cfg.instructions) ? cfg.instructions : [];
+  const texts = existing.filter((e) => typeof e === "string");
+  if (texts.some((e) => e.includes(INSTRUCTION_OPT_OUT))) return { added: false };
+  if (texts.some((e) => e.includes(INSTRUCTION_MARKER))) return { added: false };
+  cfg.instructions = [...existing, `${INSTRUCTION_MARKER}
+
+${STANDING_INSTRUCTION}`];
   return { added: true };
 }
 
@@ -1454,7 +1535,7 @@ var agentPoolHooks = (async ({ client, serverUrl }, options) => {
       const stuck = findStuck(s);
       if (stuck.length === 0) return;
       const released = [];
-      for (const { key, claim } of stuck) {
+      for (const { key, claim, reason } of stuck) {
         if (!claim.g) backfillChild(s, claim);
         const idle = idleFor(s, claim, Date.now());
         const since = Number.isFinite(idle) ? `${Math.round(idle / 1e3)}s of silence` : "no child session ever bound";
@@ -1466,7 +1547,7 @@ var agentPoolHooks = (async ({ client, serverUrl }, options) => {
             s.reaped++;
             await log(
               "warn",
-              `hung ${claim.v} on ${claim.m} after ${age}s with ${since}; aborted session ${claim.g}`,
+              reason === "overran" ? `overran ${claim.v} on ${claim.m} after ${age}s; aborted session ${claim.g}` : `hung ${claim.v} on ${claim.m} after ${age}s with ${since}; aborted session ${claim.g}`,
               { base: claim.v, model: claim.m, slot: claim.k, session: claim.g, aborted: true }
             );
             await coolForHang(claim, log);
@@ -1513,7 +1594,7 @@ var agentPoolHooks = (async ({ client, serverUrl }, options) => {
   timer.unref?.();
   void log(
     "info",
-    `reaper armed: every ${Math.round(reapMs / 1e3)}s, aborts a claim older than ${Math.round(STUCK_MIN_AGE_MS / 6e4)}m whose target has been silent ${Math.round(STUCK_IDLE_MS / 6e4)}m`
+    `reaper armed: every ${Math.round(reapMs / 1e3)}s, aborts a claim older than ${Math.round(STUCK_MIN_AGE_MS / 6e4)}m whose target has been silent ${Math.round(STUCK_IDLE_MS / 6e4)}m, or any claim past the ${Math.round(MAX_CLAIM_AGE_MS / 6e4)}m ceiling however chatty`
   );
   return {
     config: async (cfg) => {
@@ -1592,9 +1673,12 @@ var agentPoolHooks = (async ({ client, serverUrl }, options) => {
         if (!info || info.role !== "assistant" || !info.error) return;
         const haystack = JSON.stringify(info.error) ?? "";
         const status = typeof info.error.data?.statusCode === "number" ? info.error.data.statusCode : void 0;
-        if (!isLimitText(haystack) && status !== 429) return;
+        const limited = isLimitText(haystack) || status === 429;
+        const gateway5xx = status !== void 0 && status >= 500 && status <= 599;
+        const transientGateway = gateway5xx || isTransientGatewayText(haystack);
+        if (!limited && !transientGateway) return;
         const model = `${info.providerID ?? "?"}/${info.modelID ?? "?"}`;
-        if (isUnavailableText(haystack)) {
+        if (isUnavailableText(haystack) || !limited && transientGateway) {
           const transient = coolUnavailable(s, model);
           if (transient) await log("warn", `cooling ${model} for ${Math.round((transient.until - Date.now()) / 1e3)}s (${transient.reason})`);
           return;
@@ -1609,9 +1693,19 @@ var agentPoolHooks = (async ({ client, serverUrl }, options) => {
     },
     "tool.execute.before": async (input, output) => {
       if (input.tool !== "task") return;
+      const requested = output.args?.subagent_type;
+      if (typeof requested !== "string") return;
+      const manual = manualVariant(requested);
+      if (manual) {
+        await log("warn", `refused manual spawn of slot variant ${requested}; spawn "${manual}" instead`, {
+          variant: requested,
+          base: manual
+        });
+        throw new Error(
+          `${requested} is a pool slot variant and cannot be spawned by name. Naming it lets the caller pick the provider: it skips the round-robin rotation and the slot's ceiling, so one provider takes every concurrent claim. Spawn "${manual}" and let the pool choose the slot.`
+        );
+      }
       try {
-        const requested = output.args?.subagent_type;
-        if (typeof requested !== "string") return;
         await reapStuck();
         refreshCatalog(s, serverUrl);
         const snap = snapshot(s);
@@ -1633,11 +1727,6 @@ var agentPoolHooks = (async ({ client, serverUrl }, options) => {
           });
           return;
         }
-        const direct = /^(.*)-([1-9][0-9]*)$/.exec(requested);
-        if (direct && BASES.includes(direct[1])) {
-          const slot = s.slots.find((sl) => sl.index === Number(direct[2]));
-          if (slot) acquire(s, direct[1], slot, input.sessionID, claimKey(input.sessionID, input.callID));
-        }
       } catch (error) {
         await log("error", `routing failed, spawn unchanged: ${String(error)}`);
       }
@@ -1681,7 +1770,9 @@ var agentPoolHooks = (async ({ client, serverUrl }, options) => {
           };
           const total = [...snap.counts.values()].reduce((sum, n) => sum + n, 0);
           const coolingNow = [...snap.cooling.entries()].filter(([, st]) => st.until > now);
-          const hung = [...snap.own.values()].filter((c) => now - c.t > STUCK_MIN_AGE_MS && idleFor(s, c, now) >= STUCK_IDLE_MS).length;
+          const verdicts = [...snap.own.values()].map((claim) => condemnReason(s, claim, now));
+          const hung = verdicts.filter((verdict) => verdict === "hung").length;
+          const overran = verdicts.filter((verdict) => verdict === "overran").length;
           return {
             title: `agent-pool: ${total} task(s) in flight, ${coolingNow.length} model(s) cooling`,
             output: [
@@ -1695,6 +1786,7 @@ round robin in slot order, each slot taking as many turns as its weight says, so
               "",
               `${total} claim(s) in flight across ${snap.siblings.length + 1} process(es).`,
               `hung past ${Math.round(STUCK_MIN_AGE_MS / 6e4)}min with ${Math.round(STUCK_IDLE_MS / 6e4)}min silence: ${hung} (auto-aborted); reaped total: ${s.reaped}.`,
+              `overran past ${Math.round(MAX_CLAIM_AGE_MS / 6e4)}min: ${overran} (auto-aborted).`,
               `watchdog alive: last sweep ${s.lastSweep ? `${Math.max(0, Math.round((now - s.lastSweep) / 1e3))}s ago` : "never"} (every ${Math.round(reapMs / 1e3)}s).`,
               coolingNow.length === 0 ? "no models cooling down." : `cooling: ${coolingNow.map(([m, st]) => `${m} for ${Math.ceil((st.until - now) / 1e3)}s`).join(", ")}`
             ].join("\n")
@@ -1711,28 +1803,10 @@ round robin in slot order, each slot taking as many turns as its weight says, so
 });
 
 // src/plugins/context-autoupdate.ts
-import { existsSync as existsSync2, readdirSync as readdirSync2, statSync as statSync2 } from "node:fs";
+import { existsSync as existsSync2, readdirSync as readdirSync2, statSync as statSync2, mkdirSync as mkdirSync2, writeFileSync as writeFileSync2 } from "node:fs";
 import * as path2 from "node:path";
 
-// src/lib/writer-rule.ts
-import { readFileSync as readFileSync3 } from "node:fs";
-import * as path from "node:path";
-var CONTEXT_DIR = path.join(".opencode", "context");
-var WRITER = "context";
-var toPosix = (value) => value.split(path.sep).join("/");
-var compilePattern = (pattern) => {
-  const escaped = toPosix(pattern).replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
-  return new RegExp(`^${escaped}$`, "s");
-};
-var winningRule = (rule, file) => {
-  if (typeof rule === "string") return { pattern: "<whole tool>", action: rule };
-  if (!rule || typeof rule !== "object") return void 0;
-  let winner;
-  for (const [pattern, action] of Object.entries(rule)) {
-    if (compilePattern(pattern).test(file)) winner = { pattern, action: String(action) };
-  }
-  return winner;
-};
+// src/lib/jsonc.ts
 var stripJsonc = (raw) => {
   let out = "";
   let i = 0;
@@ -1771,9 +1845,36 @@ var stripJsonc = (raw) => {
   }
   return out.replace(/,(\s*[}\]])/g, "$1");
 };
+var parseJsonc = (raw) => {
+  try {
+    return JSON.parse(stripJsonc(raw));
+  } catch {
+    return void 0;
+  }
+};
+
+// src/lib/writer-rule.ts
+import { readFileSync as readFileSync3 } from "node:fs";
+import * as path from "node:path";
+var CONTEXT_DIR = path.join(".opencode", "context");
+var WRITER = "context";
+var toPosix = (value) => value.split(path.sep).join("/");
+var compilePattern = (pattern) => {
+  const escaped = toPosix(pattern).replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
+  return new RegExp(`^${escaped}$`, "s");
+};
+var winningRule = (rule, file) => {
+  if (typeof rule === "string") return { pattern: "<whole tool>", action: rule };
+  if (!rule || typeof rule !== "object") return void 0;
+  let winner;
+  for (const [pattern, action] of Object.entries(rule)) {
+    if (compilePattern(pattern).test(file)) winner = { pattern, action: String(action) };
+  }
+  return winner;
+};
 var readAgents = (raw) => {
   try {
-    const agents = JSON.parse(stripJsonc(raw)).agent;
+    const agents = parseJsonc(raw).agent;
     if (agents && typeof agents === "object" && !Array.isArray(agents)) return agents;
     return {};
   } catch {
@@ -1785,6 +1886,10 @@ var evaluatedForm = (mapDir, projectRoot) => {
   const absolute = toPosix(path.join(mapDir, "architecture.md"));
   return projectRoot ? toPosix(path.relative(projectRoot, absolute)) : absolute;
 };
+var managerForm = (mapDir, projectRoot) => {
+  const absolute = toPosix(path.join(mapDir, "manager.md"));
+  return projectRoot ? toPosix(path.relative(projectRoot, absolute)) : absolute;
+};
 var verifyWriterRule = (configPath, mapDir, projectRoot) => {
   let raw;
   try {
@@ -1816,6 +1921,18 @@ var verifyWriterRule = (configPath, mapDir, projectRoot) => {
       return `context map has more than one writer: ${offenders.join(", ")} would be granted the map by permission, evaluating "${form}". Only ${WRITER} may write the map. Narrow the grant and put the deny LAST -- opencode takes the LAST matching rule, so "${CONTEXT_DIR}/**": "deny" written after "*": "allow" is what denies it: "*": "allow", "*/${CONTEXT_DIR}/**": "deny", "${CONTEXT_DIR}/**": "deny". Both spellings are required because the evaluated path depends on the project root.`;
     }
   }
+  const managerPath = managerForm(mapDir, projectRoot);
+  const agentDefs = readAgents(raw);
+  if (agentDefs) {
+    const writers = [];
+    for (const [name, def] of Object.entries(agentDefs)) {
+      const win = winningRule(permissionOf(def), managerPath);
+      if (win?.action === "allow") writers.push(`${name} (edit rule "${win.pattern}": "${win.action}")`);
+    }
+    if (writers.length > 0) {
+      return `${CONTEXT_DIR}/manager.md is writable by permission: ${writers.join(", ")}. It is the client's own file \u2014 what they are working on, what is ratified, what every agent must respect \u2014 and no agent writes it. Deny it LAST, after any broad allow, because opencode takes the LAST matching rule: "*": "allow", "*/${CONTEXT_DIR}/manager.md": "deny", "${CONTEXT_DIR}/manager.md": "deny". Declare this on every agent above, including \`${WRITER}\`: an agent you define yourself replaces the shipped one wholesale, permission and all.`;
+    }
+  }
   return void 0;
 };
 
@@ -1842,6 +1959,51 @@ var IGNORED_SEGMENTS = /* @__PURE__ */ new Set([
   ".cache",
   ".git"
 ]);
+var MANAGER_TEMPLATE = `# Managerial directions
+
+This file is yours. No agent writes it: the context agent is explicitly denied
+permission to touch this path, and nothing changes it except you, or an agent
+acting on your explicit instruction in that conversation.
+
+It records what you want done and how you want it approached \u2014 what is being
+worked on, what comes next, what you have settled, and what every agent should
+keep in mind. It deliberately says nothing about where code lives: the source
+and the five generated context files are the only authority on that, so this
+file can never contradict the code.
+
+Add any headings you like. The four below are a convenience, not a schema \u2014
+every heading in this file is direction.
+
+## Current
+
+<!-- What is being worked on right now. Rewrite it; do not append a history. -->
+
+## Next
+
+<!-- What comes next, in order. -->
+
+## Confirmed
+
+<!-- What you have personally ratified. Nothing enters or leaves this list
+     except by your hand \u2014 no agent promotes, prunes or rewrites it. -->
+
+## Instructions
+
+<!-- Standing direction that applies beyond the current task: priorities, things
+     to care about, constraints that are not obvious from the code. -->`;
+var ensureManagerFile = (root) => {
+  try {
+    const target = path2.join(root, ".opencode", "context", "manager.md");
+    if (existsSync2(target)) return { created: false };
+    mkdirSync2(path2.dirname(target), { recursive: true });
+    writeFileSync2(target, MANAGER_TEMPLATE, { flag: "wx" });
+    return { created: true };
+  } catch (error) {
+    if (error?.code === "EEXIST") return { created: false };
+    console.warn(`[context-autoupdate] ensureManagerFile failed: ${error}`);
+    return { created: false };
+  }
+};
 var toPosix2 = (value) => value.split(path2.sep).join("/");
 var findProjectConfig = () => {
   let dir = import.meta.dir ?? path2.dirname(new URL(import.meta.url).pathname);
@@ -1885,6 +2047,7 @@ var contextAutoUpdateHooks = (async ({ client, directory }, options) => {
   });
   const root = path2.resolve(directory);
   const contextAbs = path2.join(root, CONTEXT_DIR2);
+  if (ensureManagerFile(root).created) void log("info", `created ${CONTEXT_DIR2}/manager.md`);
   const config = findProjectConfig();
   const writerProblem = config ? verifyWriterRule(config, contextAbs, root) : void 0;
   if (writerProblem) void log("error", writerProblem);
@@ -1944,7 +2107,7 @@ var contextAutoUpdateHooks = (async ({ client, directory }, options) => {
         const requeue = () => {
           for (const file of files) pending.add(file);
         };
-        const mode = existsSync2(contextAbs) ? "update" : "bootstrap";
+        const mode = existsSync2(path2.join(contextAbs, "contexts.md")) ? "update" : "bootstrap";
         init(state2, (m) => void log("warn", m));
         const snap = snapshot(state2);
         const slot = pickSlot(state2, snap);
@@ -2844,7 +3007,7 @@ var omniRouteHooks = async (input, options, deps = {}) => {
 
 // src/lib/selfupdate.ts
 import { spawn as spawn2 } from "node:child_process";
-import { closeSync, mkdirSync as mkdirSync2, openSync, readFileSync as readFileSync4, renameSync as renameSync2, rmSync, statSync as statSync3, unlinkSync as unlinkSync2, writeFileSync as writeFileSync2, writeSync } from "node:fs";
+import { closeSync, mkdirSync as mkdirSync3, openSync, readFileSync as readFileSync4, renameSync as renameSync2, rmSync, statSync as statSync3, unlinkSync as unlinkSync2, writeFileSync as writeFileSync3, writeSync } from "node:fs";
 import { homedir as homedir2 } from "node:os";
 import { dirname as dirname3, join as join6, resolve as resolve2 } from "node:path";
 var REGISTRY_LATEST = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
@@ -2869,9 +3032,17 @@ function compareSemver(a, b) {
   }
   return 0;
 }
-function readInstalledVersion(packageRoot) {
+function readInstalledVersion(packageRoot, read = (path4) => {
+  try {
+    return readFileSync4(path4, "utf8");
+  } catch {
+    return void 0;
+  }
+}) {
   try {
-    const manifest = JSON.parse(readFileSync4(join6(packageRoot, "package.json"), "utf8"));
+    const raw = read(join6(packageRoot, "package.json"));
+    if (raw === void 0) return void 0;
+    const manifest = JSON.parse(raw);
     if (manifest.name !== PACKAGE_NAME) return void 0;
     return typeof manifest.version === "string" ? manifest.version : void 0;
   } catch {
@@ -2930,8 +3101,8 @@ function readState(path4 = STATE_PATH) {
 }
 function writeState(state2, path4 = STATE_PATH) {
   try {
-    mkdirSync2(dirname3(path4), { recursive: true });
-    writeFileSync2(path4, JSON.stringify(state2));
+    mkdirSync3(dirname3(path4), { recursive: true });
+    writeFileSync3(path4, JSON.stringify(state2));
   } catch {
   }
 }
@@ -2957,7 +3128,7 @@ function acquireLock(path4 = LOCK_PATH, now = Date.now()) {
     };
   };
   try {
-    mkdirSync2(dirname3(path4), { recursive: true });
+    mkdirSync3(dirname3(path4), { recursive: true });
     return claim();
   } catch {
     let orphaned = false;
@@ -3146,7 +3317,7 @@ var LaCode = (async (input, options) => {
         await log("info", `commands: added ${cmds.added.join(", ")}; kept ${cmds.kept.join(", ") || "none"} already defined`);
       }
       if (applyInstructions(cfg).added) {
-        await log("info", "instructions: added the standing context-map rule (no user instructions were present)");
+        await log("info", "instructions: ensured the standing context-map rule is present");
       }
       await omniroute.config?.(cfg);
       await pool.config?.(cfg);