Release iso-harness 0.8.0, iso-trace 0.5.0, and iso-orchestrator 0.2.0

Author: CharGrnmn

package-lock.json

@@ -1,5 +1,21 @@
 # @razroo/iso-harness
 
+## 0.8.0
+
+### Minor Changes
+
+- Add optional per-target root instruction addenda to `iso-harness` so
+  shared AGENTS text can stay harness-neutral while OpenCode-only guidance
+  is emitted separately.
+
+  Add `inspectSession()` / `inspectSessions()` to `iso-trace` for
+  harness-agnostic worker/session summaries, and surface OpenCode session
+  titles in normalized session metadata.
+
+  Add heartbeat and renewable lease primitives to `iso-orchestrator` so
+  consumers can track worker liveness and ownership without introducing
+  harness-specific dispatch APIs.
+
 ## 0.7.0
 
 ### Minor Changes

packages/iso-harness/CHANGELOG.md

@@ -9,20 +9,27 @@ file layout each harness actually reads.
 ```
 iso/                              →  CLAUDE.md                    (Claude Code)
 ├── instructions.md                  .claude/agents/*.md
-├── mcp.json                         .claude/commands/*.md
+├── instructions.agents.md*          .claude/commands/*.md
+├── instructions.claude.md*          .mcp.json
+├── instructions.cursor.md*       →  AGENTS.md                    (Codex + OpenCode + Pi)
+├── instructions.opencode.md*        .codex/config.toml
+├── mcp.json                         .opencode/agents/*.md
+│                                     .opencode/skills/*.md
+│                                     .opencode/instructions.md*  (OpenCode-only addendum)
+│                                     .opencode/opencode-model-fallback.json  (optional; from `opencodeModelFallback` in iso/config.json)
+│                                     opencode.json
+│                                  →  .cursor/rules/*.mdc          (Cursor)
+│                                     .cursor/mcp.json
+│                                  →  .pi/skills/*/SKILL.md        (Pi)
+│                                     .pi/prompts/*.md
 ├── agents/                          .mcp.json
-│   └── researcher.md             →  AGENTS.md                    (Codex + OpenCode + Pi)
-└── commands/                        .codex/config.toml
-    └── review.md                                                         .opencode/agents/*.md
-                                     .opencode/skills/*.md
-                                     .opencode/opencode-model-fallback.json  (optional; from `opencodeModelFallback` in iso/config.json)
-                                     opencode.json
-                                  →  .cursor/rules/*.mdc          (Cursor)
-                                     .cursor/mcp.json
-                                  →  .pi/skills/*/SKILL.md        (Pi)
-                                     .pi/prompts/*.md
+│   └── researcher.md
+└── commands/
+    └── review.md
 ```
 
+Files marked with `*` are optional.
+
 ## Quickstart
 
 ```bash
@@ -53,6 +60,10 @@ iso-harness build --watch                 # rebuild on every change under iso/
 ```
 iso/
 ├── instructions.md       # root prompt → CLAUDE.md / AGENTS.md / .cursor/rules/main.mdc
+├── instructions.agents.md   # optional addendum for shared AGENTS.md targets
+├── instructions.claude.md   # optional Claude-only root addendum
+├── instructions.cursor.md   # optional Cursor-only root addendum
+├── instructions.opencode.md # optional OpenCode-only addendum, loaded via opencode.json.instructions
 ├── config.json           # optional — targets.* merges + opencodeModelFallback file emit
 ├── mcp.json              # shared MCP server definitions
 ├── agents/               # subagents
@@ -151,6 +162,19 @@ explicit hatches keep harness-specific features possible:
    plugin (`retryable_error_patterns`, global `fallback_models`, etc.).
    OpenCode-only; other harnesses ignore it.
 
+### Root instruction addenda
+
+`instructions.md` is still the shared base prompt. Optional sibling files let
+you add harness-specific root guidance without forking the whole source:
+
+- `instructions.agents.md` appends only to the shared `AGENTS.md` output used by Codex, OpenCode, and Pi.
+- `instructions.claude.md` appends only to `CLAUDE.md`.
+- `instructions.cursor.md` appends only to `.cursor/rules/main.mdc`.
+- `instructions.opencode.md` is emitted to `.opencode/instructions.md` and automatically added to `opencode.json.instructions`.
+
+This is especially useful when OpenCode needs extra orchestration guidance
+that should not leak into the shared `AGENTS.md` file that Codex and Pi also read.
+
 ```json
 // iso/config.json
 {

packages/iso-harness/README.md

@@ -1,6 +1,6 @@
 {
   "name": "@razroo/iso-harness",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "One config for every coding agent — Cursor, Claude Code, Codex, OpenCode, Pi.",
   "type": "module",
   "bin": {

packages/iso-harness/package.json

@@ -2,6 +2,13 @@ import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { parse as parseFrontmatter } from './frontmatter.mjs';
 
+const INSTRUCTION_VARIANTS = [
+  'agents',
+  'claude',
+  'cursor',
+  'opencode',
+];
+
 async function readIfExists(p) {
   try {
     return await fs.readFile(p, 'utf8');
@@ -52,6 +59,11 @@ export async function loadSource(sourceDir) {
   }
 
   const instructions = await readIfExists(path.join(abs, 'instructions.md'));
+  const instructionVariants = {};
+  for (const name of INSTRUCTION_VARIANTS) {
+    const value = await readIfExists(path.join(abs, `instructions.${name}.md`));
+    if (value != null) instructionVariants[name] = value;
+  }
   const mcpRaw = await readIfExists(path.join(abs, 'mcp.json'));
   const configRaw = await readIfExists(path.join(abs, 'config.json'));
 
@@ -83,12 +95,48 @@ export async function loadSource(sourceDir) {
     sourceDir: abs,
     config,
     instructions: instructions ?? '',
+    instructionVariants,
     mcp,
     agents,
     commands,
   };
 }
 
+function joinInstructionParts(parts) {
+  const present = parts.filter((part) => typeof part === 'string' && part.trim());
+  if (present.length === 0) return '';
+  let out = present[0];
+  for (const part of present.slice(1)) {
+    out = `${out.replace(/\s+$/, '')}\n\n${part.replace(/^\s+/, '')}`;
+  }
+  return out;
+}
+
+export function instructionsForTarget(source, target) {
+  switch (target) {
+    case 'claude':
+      return joinInstructionParts([source.instructions, source.instructionVariants?.claude]);
+    case 'cursor':
+      return joinInstructionParts([source.instructions, source.instructionVariants?.cursor]);
+    case 'codex':
+    case 'pi':
+      return joinInstructionParts([source.instructions, source.instructionVariants?.agents]);
+    case 'opencode':
+      return joinInstructionParts([source.instructions, source.instructionVariants?.agents]);
+    default:
+      return source.instructions ?? '';
+  }
+}
+
+export function supplementalInstructionsForTarget(source, target) {
+  switch (target) {
+    case 'opencode':
+      return source.instructionVariants?.opencode ?? '';
+    default:
+      return '';
+  }
+}
+
 export function targetOverride(item, target) {
   const t = item.targets?.[target];
   if (t === 'skip' || t === false) return { skip: true };

packages/iso-harness/src/source.mjs

@@ -2,7 +2,7 @@ import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { stringify as toFrontmatter } from '../frontmatter.mjs';
 import { writeFile, writeJson } from '../fs-utils.mjs';
-import { targetOverride } from '../source.mjs';
+import { instructionsForTarget, targetOverride } from '../source.mjs';
 
 function claudeTools(tools) {
   if (!tools) return undefined;
@@ -46,9 +46,10 @@ export async function emitClaude(src, outDir, opts = {}) {
   };
   const roleMap = await loadResolvedRoleMap(outDir);
 
-  if (src.instructions) {
+  const instructions = instructionsForTarget(src, 'claude');
+  if (instructions) {
     const p = path.join(outDir, 'CLAUDE.md');
-    await push(p, src.instructions.endsWith('\n') ? src.instructions : src.instructions + '\n');
+    await push(p, instructions.endsWith('\n') ? instructions : instructions + '\n');
   }
 
   for (const agent of src.agents) {

packages/iso-harness/src/targets/claude.mjs

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import { promises as fs } from 'node:fs';
 import { writeFile } from '../fs-utils.mjs';
+import { instructionsForTarget } from '../source.mjs';
 
 function tomlString(v) {
   return `"${String(v).replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
@@ -64,9 +65,10 @@ export async function emitCodex(src, outDir, opts = {}) {
     written.push({ path: p, bytes });
   };
 
-  if (src.instructions) {
+  const instructions = instructionsForTarget(src, 'codex');
+  if (instructions) {
     const p = path.join(outDir, 'AGENTS.md');
-    await push(p, src.instructions.endsWith('\n') ? src.instructions : src.instructions + '\n');
+    await push(p, instructions.endsWith('\n') ? instructions : instructions + '\n');
   }
 
   if (Object.keys(src.mcp.servers).length > 0) {

packages/iso-harness/src/targets/codex.mjs

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import { stringify as toFrontmatter } from '../frontmatter.mjs';
 import { writeFile, writeJson } from '../fs-utils.mjs';
-import { targetOverride } from '../source.mjs';
+import { instructionsForTarget, targetOverride } from '../source.mjs';
 
 export async function emitCursor(src, outDir, opts = {}) {
   const written = [];
@@ -10,13 +10,14 @@ export async function emitCursor(src, outDir, opts = {}) {
     written.push({ path: p, bytes });
   };
 
-  if (src.instructions) {
+  const instructions = instructionsForTarget(src, 'cursor');
+  if (instructions) {
     const data = {
       description: 'Project instructions',
       alwaysApply: true,
     };
     const p = path.join(outDir, '.cursor', 'rules', 'main.mdc');
-    await push(p, toFrontmatter({ data, body: src.instructions }));
+    await push(p, toFrontmatter({ data, body: instructions }));
   }
 
   // Cursor has no native subagents or slash commands; emit agent prompts as

packages/iso-harness/src/targets/cursor.mjs

@@ -2,7 +2,13 @@ import path from 'node:path';
 import { promises as fs } from 'node:fs';
 import { stringify as toFrontmatter } from '../frontmatter.mjs';
 import { writeFile, writeJson } from '../fs-utils.mjs';
-import { targetOverride } from '../source.mjs';
+import { instructionsForTarget, supplementalInstructionsForTarget, targetOverride } from '../source.mjs';
+
+function mergeInstructionRefs(existing, extra) {
+  const base = Array.isArray(existing) ? existing : existing ? [existing] : [];
+  if (!extra) return base;
+  return [...new Set([...base, extra])];
+}
 
 async function readJsonIfExists(p) {
   try {
@@ -34,9 +40,10 @@ export async function emitOpenCode(src, outDir, opts = {}) {
     written.push({ path: p, bytes });
   };
 
-  if (src.instructions) {
+  const instructions = instructionsForTarget(src, 'opencode');
+  if (instructions) {
     const p = path.join(outDir, 'AGENTS.md');
-    await push(p, src.instructions.endsWith('\n') ? src.instructions : src.instructions + '\n');
+    await push(p, instructions.endsWith('\n') ? instructions : instructions + '\n');
   }
 
   // Load iso-route's opencode.json once so we can (a) fall back to its
@@ -46,6 +53,15 @@ export async function emitOpenCode(src, outDir, opts = {}) {
   // below with the later merge-write on opencode.json.
   const opencodeJsonPath = path.join(outDir, 'opencode.json');
   const existingConfig = opts.dryRun ? {} : await readJsonIfExists(opencodeJsonPath);
+  const opencodeSupplement = supplementalInstructionsForTarget(src, 'opencode');
+  const opencodeSupplementPath = path.join(outDir, '.opencode', 'instructions.md');
+
+  if (opencodeSupplement) {
+    await push(
+      opencodeSupplementPath,
+      opencodeSupplement.endsWith('\n') ? opencodeSupplement : opencodeSupplement + '\n',
+    );
+  }
 
   for (const agent of src.agents) {
     const { skip, override } = targetOverride(agent, 'opencode');
@@ -97,7 +113,8 @@ export async function emitOpenCode(src, outDir, opts = {}) {
   const opencodeExtras = src.config?.targets?.opencode ?? {};
   const hasMcp = Object.keys(src.mcp.servers).length > 0;
   const hasExtras = Object.keys(opencodeExtras).length > 0;
-  if (hasMcp || hasExtras) {
+  const needsInstructionRef = Boolean(opencodeSupplement);
+  if (hasMcp || hasExtras || needsInstructionRef) {
     // Reuse the `existingConfig` loaded at the top — re-reading could race
     // with intermediate per-agent file writes on slower filesystems and is
     // wasted I/O. `@razroo/iso-route` writes model routing fields to
@@ -122,6 +139,9 @@ export async function emitOpenCode(src, outDir, opts = {}) {
     for (const [k, v] of Object.entries(opencodeExtras)) {
       output[k] = v;
     }
+    if (needsInstructionRef) {
+      output.instructions = mergeInstructionRefs(output.instructions, '.opencode/instructions.md');
+    }
     await push(opencodeJsonPath, output, writeJson);
   }
 

packages/iso-harness/src/targets/opencode.mjs

@@ -2,7 +2,7 @@ import path from 'node:path';
 import { promises as fs } from 'node:fs';
 import { stringify as toFrontmatter } from '../frontmatter.mjs';
 import { writeFile, writeJson } from '../fs-utils.mjs';
-import { targetOverride } from '../source.mjs';
+import { instructionsForTarget, targetOverride } from '../source.mjs';
 
 async function readJsonIfExists(p) {
   try {
@@ -50,9 +50,10 @@ export async function emitPi(src, outDir, opts = {}) {
     written.push({ path: p, bytes });
   };
 
-  if (src.instructions) {
+  const instructions = instructionsForTarget(src, 'pi');
+  if (instructions) {
     const p = path.join(outDir, 'AGENTS.md');
-    await push(p, src.instructions.endsWith('\n') ? src.instructions : src.instructions + '\n');
+    await push(p, instructions.endsWith('\n') ? instructions : instructions + '\n');
   }
 
   for (const agent of src.agents) {