@open-mercato/cli 0.6.7 → 0.6.8-canary.319.1.5b4be4bc52

package/dist/agentic/shared/ai/trackers/github.md

@@ -1,8 +1,8 @@
 # Tracker provider: GitHub
 
-This file is the GitHub implementation of the tracker operations contract (see `TEMPLATE.md` for the contract itself). Every skill in the collection performs issue/PR state management through **named tracker operations** — `**get-issue**`, `**comment-pr**`, and so on — and this file defines what each operation means for GitHub, using the `gh` CLI.
+This file is the GitHub implementation of the tracker operations contract (see `TEMPLATE.md` for the contract itself). Skills perform issue/PR state management through **named tracker operations** — `**get-issue**`, `**comment-pr**`, and so on — and this file defines what each operation means for GitHub, using the `gh` CLI.
 
-How it is used at runtime: `om-setup-agent-pipeline` copies this file into the repository at `.ai/trackers/github.md`, and the config's `tracker` field selects it. When a skill says "tracker operation **get-pr**", execute the command documented under that operation heading in the repo's copy. The repo's copy is authoritative: teams extend or override any operation by editing it — add flags, swap a command, append repo-specific conventions — and every skill picks the change up on its next run. An operation not covered by an edit keeps its behavior from this file's text as copied.
+At runtime: `om-setup-agent-pipeline` copies this file into the repository at `.ai/trackers/github.md`, and the config's `tracker` field selects it. When a skill says "tracker operation **get-pr**", execute the command documented under that operation heading in the repo's copy. The repo's copy is authoritative: teams extend or override any operation by editing it, and every skill picks the change up on its next run. An operation not covered by an edit keeps its behavior from this file's text as copied.
 
 ## Prerequisites
 
@@ -14,7 +14,7 @@ How it is used at runtime: `om-setup-agent-pipeline` copies this file into the r
 - Issue and PR identifiers are numbers; in text they are written `#123`.
 - A PR is linked to the issue it resolves with `Fixes #{issueId}` (or `Closes #{issueId}`) in the PR body; GitHub then closes the issue on merge. To reference without auto-closing, use a plain issue link.
 - PRs open as **drafts** when a skill says so; a human (or **mark-pr-ready**) promotes them.
-- Claim/lock signals on an issue or PR are: assignee set to the automation user, the `in-progress` label, and a `🤖`-prefixed claim comment. All three are set on claim; the label is guarded (below).
+- Claim/lock signals on an issue or PR are: assignee set to the automation user, the `in-progress` label, and a `🤖`-prefixed claim comment. All three are set on claim; the label is guarded (below). The `ci-monitoring` label is **not** a claim/lock signal: it marks a PR whose work is finished and already reported while an agent watches CI, so a PR carrying `ci-monitoring` without any of the three signals above MUST be treated as unclaimed and is free to claim.
 - Long, multi-line comment bodies are posted with `--body-file` (or a heredoc via process substitution) so formatting is preserved.
 - CI status truth comes from **get-pr-checks**; the set of *required* checks comes from **get-required-checks** (branch protection). When branch protection is not readable (404), treat every reported check as required.
 
@@ -98,6 +98,84 @@ BASE_BRANCH=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'
 [ -z "$BASE_BRANCH" ] && BASE_BRANCH="main"
 ```
 
+### Public session-share artifacts
+
+#### publish-session-share
+`{owner}/{repo}`, `{branch}`, `{shareName}`, and a local `{bundleDir}` → atomically publish the four reviewed session-share artifacts on a new public branch and return repository, branch, commit, branch URL, and raw artifact URLs as JSON.
+
+This operation is intentionally strict: the repository must already be public; the branch must be a new slash-free `session-share-…` ref; and the bundle directory must contain regular, non-symlinked `session.json`, `generated-files.zip`, `manifest.json`, and `privacy-report.json` files within the documented size cap. Git blobs, a tree, and a commit are created first; the public ref is created last, so a preparation failure does not expose a partial branch.
+
+```bash
+TARGET_REPO="{owner}/{repo}"
+SHARE_BRANCH="{branch}"
+SHARE_NAME="{shareName}"
+BUNDLE_DIR="{bundleDir}"
+printf '%s' "$TARGET_REPO" | grep -Eq '^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$' || exit 1
+printf '%s' "$SHARE_NAME" | grep -Eq '^[a-z0-9][a-z0-9-]{1,46}[a-z0-9]$' || exit 1
+[ "$SHARE_BRANCH" = "session-share-$SHARE_NAME" ] || exit 1
+[ "$(gh repo view "$TARGET_REPO" --json visibility --jq .visibility)" = "PUBLIC" ] || exit 1
+gh api "repos/${TARGET_REPO}/git/ref/heads/${SHARE_BRANCH}" >/dev/null 2>&1 && exit 1
+
+SESSION_SHARE_TMP=$(mktemp -d)
+trap 'rm -rf "$SESSION_SHARE_TMP"' EXIT HUP INT TERM
+printf '[]\n' > "$SESSION_SHARE_TMP/tree.json"
+TOTAL_BYTES=0
+for ARTIFACT in session.json generated-files.zip manifest.json privacy-report.json; do
+  ARTIFACT_PATH="$BUNDLE_DIR/$ARTIFACT"
+  [ -f "$ARTIFACT_PATH" ] && [ ! -L "$ARTIFACT_PATH" ] || exit 1
+  ARTIFACT_BYTES=$(wc -c < "$ARTIFACT_PATH" | tr -d ' ')
+  TOTAL_BYTES=$((TOTAL_BYTES + ARTIFACT_BYTES))
+  [ "$ARTIFACT_BYTES" -le 26214400 ] && [ "$TOTAL_BYTES" -le 31457280 ] || exit 1
+done
+
+for ARTIFACT in session.json generated-files.zip manifest.json privacy-report.json; do
+  ARTIFACT_PATH="$BUNDLE_DIR/$ARTIFACT"
+  base64 < "$ARTIFACT_PATH" | tr -d '\n' > "$SESSION_SHARE_TMP/content.b64"
+  BLOB_SHA=$(jq -n --rawfile content "$SESSION_SHARE_TMP/content.b64" '{content:$content,encoding:"base64"}' \
+    | gh api -X POST "repos/${TARGET_REPO}/git/blobs" --input - --jq .sha) || exit 1
+  jq --arg path "$ARTIFACT" --arg sha "$BLOB_SHA" \
+    '. + [{path:$path,mode:"100644",type:"blob",sha:$sha}]' \
+    "$SESSION_SHARE_TMP/tree.json" > "$SESSION_SHARE_TMP/tree.next.json" || exit 1
+  mv "$SESSION_SHARE_TMP/tree.next.json" "$SESSION_SHARE_TMP/tree.json"
+done
+
+DEFAULT_BRANCH=$(gh repo view "$TARGET_REPO" --json defaultBranchRef --jq .defaultBranchRef.name) || exit 1
+BASE_COMMIT=$(gh api "repos/${TARGET_REPO}/git/ref/heads/${DEFAULT_BRANCH}" --jq .object.sha) || exit 1
+BASE_TREE=$(gh api "repos/${TARGET_REPO}/git/commits/${BASE_COMMIT}" --jq .tree.sha) || exit 1
+TREE_SHA=$(jq -n --arg base "$BASE_TREE" --slurpfile entries "$SESSION_SHARE_TMP/tree.json" \
+  '{base_tree:$base,tree:$entries[0]}' \
+  | gh api -X POST "repos/${TARGET_REPO}/git/trees" --input - --jq .sha) || exit 1
+COMMIT_SHA=$(jq -n --arg message "session share ${SHARE_NAME}" --arg tree "$TREE_SHA" --arg parent "$BASE_COMMIT" \
+  '{message:$message,tree:$tree,parents:[$parent]}' \
+  | gh api -X POST "repos/${TARGET_REPO}/git/commits" --input - --jq .sha) || exit 1
+jq -n --arg ref "refs/heads/${SHARE_BRANCH}" --arg sha "$COMMIT_SHA" '{ref:$ref,sha:$sha}' \
+  | gh api -X POST "repos/${TARGET_REPO}/git/refs" --input - >/dev/null || exit 1
+
+jq -n \
+  --arg repository "$TARGET_REPO" \
+  --arg branch "$SHARE_BRANCH" \
+  --arg commit "$COMMIT_SHA" \
+  --arg branchUrl "https://github.com/${TARGET_REPO}/tree/${SHARE_BRANCH}" \
+  --arg sessionUrl "https://raw.githubusercontent.com/${TARGET_REPO}/${SHARE_BRANCH}/session.json" \
+  --arg archiveUrl "https://raw.githubusercontent.com/${TARGET_REPO}/${SHARE_BRANCH}/generated-files.zip" \
+  --arg manifestUrl "https://raw.githubusercontent.com/${TARGET_REPO}/${SHARE_BRANCH}/manifest.json" \
+  --arg privacyUrl "https://raw.githubusercontent.com/${TARGET_REPO}/${SHARE_BRANCH}/privacy-report.json" \
+  '{repository:$repository,branch:$branch,commit:$commit,branchUrl:$branchUrl,artifacts:{session:$sessionUrl,archive:$archiveUrl,manifest:$manifestUrl,privacy:$privacyUrl}}'
+```
+
+#### delete-session-share
+`{owner}/{repo}`, `{branch}`, and `{shareName}` → remove only the exact derived session-share ref after a failed issue creation or an explicit retention cleanup request. Deleting a public ref cannot guarantee erasure from clones, forks, caches, logs, or archives.
+
+```bash
+TARGET_REPO="{owner}/{repo}"
+SHARE_BRANCH="{branch}"
+SHARE_NAME="{shareName}"
+printf '%s' "$TARGET_REPO" | grep -Eq '^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$' || exit 1
+printf '%s' "$SHARE_NAME" | grep -Eq '^[a-z0-9][a-z0-9-]{1,46}[a-z0-9]$' || exit 1
+[ "$SHARE_BRANCH" = "session-share-$SHARE_NAME" ] || exit 1
+gh api -X DELETE "repos/${TARGET_REPO}/git/refs/heads/${SHARE_BRANCH}"
+```
+
 ### Issues
 
 #### get-issue
@@ -109,7 +187,9 @@ gh issue view {issueId} --repo {owner}/{repo} --json number,title,body,state,aut
 #### search-issues
 Query (text, `in:title,body`, state) → matching issues.
 ```bash
-gh issue list --repo {owner}/{repo} --state open --search "<query> in:title,body" --json number,title,url
+ISSUE_STATE="{state}"
+case "$ISSUE_STATE" in open|closed|all) ;; *) exit 1 ;; esac
+gh issue list --repo {owner}/{repo} --state "$ISSUE_STATE" --search "<query> in:title,body" --json number,title,url
 ```
 
 #### create-issue
@@ -130,6 +210,12 @@ gh issue close {issueId} --repo {owner}/{repo} --reason completed --comment "<co
 gh issue comment {issueId} --repo {owner}/{repo} --body "<body>"
 ```
 
+#### update-issue
+`{issueId}`, new title and/or body (use a body-file for multi-line bodies). Edits the issue's own fields; does not touch labels or assignees (those have their own operations).
+```bash
+gh issue edit {issueId} --repo {owner}/{repo} --title "<title>" --body-file <file>
+```
+
 #### assign-issue / unassign-issue
 ```bash
 gh issue edit {issueId} --repo {owner}/{repo} --add-assignee "<login>"
@@ -151,6 +237,12 @@ gh api repos/{owner}/{repo}/issues/comments/{commentId} --jq '{body,user:.user.l
 gh api repos/{owner}/{repo}/issues/{number}/comments --jq '.[] | {id,user:.user.login,body}'
 ```
 
+#### update-comment
+`{commentId}`, new body → rewrite an existing conversation comment in place (works for issue and PR conversation comments alike). This is how marker-idempotent comments (label rationale, verification, claim take-overs) are updated on re-runs: find your `🤖 …` marker via **list-issue-comments**, then update that comment instead of posting a new one. Use a body file so multi-line bodies survive.
+```bash
+gh api -X PATCH repos/{owner}/{repo}/issues/comments/{commentId} -F body=@<path>
+```
+
 ### Pull requests
 
 #### get-pr
@@ -181,6 +273,17 @@ PR_URL=$(gh pr view --json url --jq .url)
 PR_NUMBER=$(gh pr view --json number --jq .number)
 ```
 
+#### update-pr
+`{prNumber}`, new title and/or new body → the PR's own title/body rewritten in place (not a comment), e.g. reframing a doc-originated spec PR that grew a feature implementation. Pass whichever of `--title` / `--body-file` changed; omit the other. Use a body file so multi-line bodies survive.
+```bash
+gh pr edit {prNumber} --title "<title>"
+gh pr edit {prNumber} --body-file <path-or-process-substitution>
+```
+If `gh pr edit` silently no-ops in this repo (some GitHub setups do), fall back to the REST API:
+```bash
+gh api -X PATCH repos/{owner}/{repo}/pulls/{prNumber} -f title="<title>" -f body="$(cat <path>)"
+```
+
 #### comment-pr
 `{prNumber}`, body. For long structured comments:
 ```bash
@@ -365,6 +468,7 @@ gh label create skip-qa           --color 0e8a16 --description "Low risk, QA not
 gh label create qa-approved       --color 0e8a16 --description "Manual QA passed"
 gh label create qa-self-verified  --color c5def5 --description "Self-QA exception used"
 gh label create in-progress       --color c5def5 --description "An automated skill is working on this"
+gh label create ci-monitoring     --color 00b8d9 --description "Work complete and reported; agent is watching CI results"
 gh label create do-not-close      --color c5def5 --description "Humans only: never auto-close this issue"
 gh label create priority-low      --color e4e669 --description "Cosmetic or follow-up work"
 gh label create priority-medium   --color fbca04 --description "Ordinary bug or feature"

package/dist/agentic/shared/scripts/agent-harness-tool-server.mjs

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs'
+import path from 'node:path'
+import process from 'node:process'
+
+const MAX_READ_BYTES = 256 * 1024
+const MAX_WRITE_BYTES = 256 * 1024
+const SAFE_TEXT_EXTENSIONS = new Set([
+  '.cjs', '.css', '.graphql', '.html', '.js', '.json', '.jsx', '.md', '.mdx',
+  '.mjs', '.prisma', '.sql', '.ts', '.tsx', '.txt', '.xml', '.yaml', '.yml',
+])
+const FORBIDDEN_SEGMENTS = new Set(['.git', '.docker', '.kube', '.aws', '.ssh', '.codex', '.claude', '.next', 'dist'])
+const FORBIDDEN_BASENAMES = new Set([
+  '.npmrc', '.netrc', '.pypirc', '.git-credentials', 'secrets.json', 'credentials.json',
+  'service-account-credentials.json',
+])
+const FORBIDDEN_SECRET_EXTENSIONS = new Set(['.key', '.pem', '.p12', '.pfx'])
+// Declarative provenance for a read outside the canonical example root. The server does
+// NOT authorize on it — the read allowlist still governs what may be read — but it refuses
+// an unrecognized value so the runner trace cannot carry an arbitrary string into the
+// evaluator's reason-gated fallback accounting. Mirrors `cases.schema.json`.
+const INSTALLED_FALLBACK_REASON_CODES = new Set([
+  'SPECIALIST_ROUTE_NOT_DECLARED',
+  'INSTALLED_VERSION_CONTRACT_MISMATCH',
+])
+
+function fail(message) {
+  process.stderr.write(`agent-harness-tool-server: ${message}\n`)
+  process.exit(2)
+}
+
+function isInside(root, candidate) {
+  const relative = path.relative(root, candidate)
+  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative))
+}
+
+function isInstalledSourcePath(value, allowPatterns) {
+  const normalized = value.replaceAll('\\', '/')
+  const segments = normalized.split('/')
+  if (segments.length < 5 || segments[0] !== 'node_modules' || segments[1] !== '@open-mercato' || segments[3] !== 'src') return false
+  if (!segments[2] || segments.slice(4).some((entry) => !entry)) return false
+  return allowPatterns || !normalized.includes('*') && !normalized.includes('?')
+}
+
+function safeRelative(value, { allowInstalledSourcePatterns = false } = {}) {
+  if (typeof value !== 'string' || !value || value.includes('\0') || path.isAbsolute(value)) return false
+  const normalized = value.replaceAll('\\', '/')
+  if (normalized === '.' || normalized.startsWith('../') || normalized.includes('/../')) return false
+  const segments = normalized.split('/')
+  const basename = segments.at(-1) ?? ''
+  const installedSource = segments.includes('node_modules')
+  if (installedSource && !isInstalledSourcePath(normalized, allowInstalledSourcePatterns)) return false
+  if ((installedSource ? segments.slice(4) : segments).some((entry) => FORBIDDEN_SEGMENTS.has(entry))) return false
+  if (normalized === '.ai/harness' || normalized.startsWith('.ai/harness/')) return false
+  if (basename === '.env' || basename.startsWith('.env.') || FORBIDDEN_BASENAMES.has(basename)) return false
+  return !FORBIDDEN_SECRET_EXTENSIONS.has(path.extname(basename).toLowerCase())
+}
+
+function globToRegExp(pattern) {
+  let source = '^'
+  for (let index = 0; index < pattern.length; index += 1) {
+    const char = pattern[index]
+    if (char === '*' && pattern[index + 1] === '*') { source += '.*'; index += 1 }
+    else if (char === '*') source += '[^/]*'
+    else if (char === '?') source += '[^/]'
+    else source += char.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  }
+  return new RegExp(`${source}$`)
+}
+
+const rootArg = process.argv[2]
+const mode = process.argv[3]
+let allowedReads
+let allowedWrites
+let immutableRoots
+try { allowedReads = JSON.parse(process.argv[4] ?? '[]') } catch { fail('allowed read set is invalid JSON') }
+try { allowedWrites = JSON.parse(process.argv[5] ?? '[]') } catch { fail('allowed write set is invalid JSON') }
+try { immutableRoots = JSON.parse(process.env.OM_HARNESS_IMMUTABLE_ROOTS ?? '[]') } catch { fail('immutable root set is invalid JSON') }
+if (!path.isAbsolute(rootArg ?? '')) fail('root must be absolute')
+if (!['read-only', 'writable'].includes(mode)) fail('mode must be read-only or writable')
+if (!Array.isArray(allowedReads) || allowedReads.some((entry) => !safeRelative(entry, { allowInstalledSourcePatterns: true }) || ['*', '**'].includes(entry))) fail('allowed read set is invalid')
+if (!Array.isArray(allowedWrites) || allowedWrites.some((entry) => !safeRelative(entry))) fail('allowed write set is invalid')
+if (!Array.isArray(immutableRoots) || immutableRoots.some((entry) => !safeRelative(entry) || entry.includes('*') || entry.includes('?'))) fail('immutable root set is invalid')
+const root = fs.realpathSync(rootArg)
+const readMatchers = allowedReads.map(globToRegExp)
+const writeMatchers = allowedWrites.map(globToRegExp)
+const immutablePrefixes = immutableRoots.map((entry) => entry.replaceAll('\\', '/'))
+
+// Root immutability precedence: declared read-only roots are resolved BEFORE the write
+// allowlist, so a broader writable grant such as `src/modules/**` can never reach inside one.
+function isImmutablePath(normalized) {
+  return immutablePrefixes.some((prefix) => normalized === prefix || normalized.startsWith(`${prefix}/`))
+}
+
+function resolveRead(relative) {
+  if (!safeRelative(relative)) throw new Error('path is outside the allowed app context')
+  const normalized = relative.replaceAll('\\', '/')
+  if (!readMatchers.some((matcher) => matcher.test(normalized))) throw new Error('path is outside the case read allowlist')
+  const lexical = path.resolve(root, relative)
+  if (!isInside(root, lexical)) throw new Error('path escapes the app root')
+  const real = fs.realpathSync(lexical)
+  if (isInstalledSourcePath(normalized, false)) {
+    const dependencyRoot = fs.realpathSync(path.join(root, 'node_modules'))
+    if (!isInside(dependencyRoot, real)) throw new Error('installed source resolves outside the protected dependency root')
+  } else if (!isInside(root, real)) throw new Error('path resolves outside the app root')
+  const stat = fs.statSync(real)
+  if (!stat.isFile() || stat.size > MAX_READ_BYTES) throw new Error('path must be a bounded regular file')
+  if (!SAFE_TEXT_EXTENSIONS.has(path.extname(real).toLowerCase()) && path.basename(real) !== 'AGENTS.md') throw new Error('path is not an allowed text file')
+  return { real, stat }
+}
+
+function resolveWrite(relative) {
+  if (mode !== 'writable') throw new Error('writes are disabled for this evaluation')
+  if (!safeRelative(relative)) throw new Error('path is outside the case write allowlist')
+  const normalized = relative.replaceAll('\\', '/')
+  if (isImmutablePath(normalized)) throw new Error('path is inside a read-only declared root and can never be written')
+  if (!writeMatchers.some((matcher) => matcher.test(normalized))) throw new Error('path is outside the case write allowlist')
+  const lexical = path.resolve(root, relative)
+  if (!isInside(root, lexical)) throw new Error('path escapes the app root')
+  let cursor = path.dirname(lexical)
+  const missing = []
+  while (cursor !== root && !fs.existsSync(cursor)) { missing.push(cursor); cursor = path.dirname(cursor) }
+  if (!isInside(root, cursor)) throw new Error('write ancestor escapes the app root')
+  for (let current = cursor; current !== root; current = path.dirname(current)) {
+    const stat = fs.lstatSync(current)
+    if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('write ancestor must be a regular directory')
+  }
+  if (fs.existsSync(lexical)) {
+    const stat = fs.lstatSync(lexical)
+    if (!stat.isFile() || stat.isSymbolicLink() || !isInside(root, fs.realpathSync(lexical))) throw new Error('write target must be a contained regular file')
+  }
+  for (const directory of missing.reverse()) fs.mkdirSync(directory, { mode: 0o700 })
+  return lexical
+}
+
+const tools = [
+  {
+    name: 'read',
+    description: 'Read one exact app-relative instruction, fact, source, or allowed target file. Fact-linked @open-mercato package source reads are allowed; absolute paths, discovery, credentials, dependency writes, Git, and harness internals are rejected.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['path'],
+      properties: {
+        path: { type: 'string' },
+        reason: { type: 'string', enum: [...INSTALLED_FALLBACK_REASON_CODES] },
+        capabilityId: { type: 'string' },
+      },
+    },
+  },
+  ...(mode === 'writable' ? [{
+    name: 'write',
+    description: 'Replace one exact app-relative file declared in the current case write allowlist. The content must be the complete file.',
+    inputSchema: { type: 'object', additionalProperties: false, required: ['path', 'content'], properties: { path: { type: 'string' }, content: { type: 'string' } } },
+  }] : []),
+]
+
+function result(id, value) {
+  process.stdout.write(`${JSON.stringify({ jsonrpc: '2.0', id, result: value })}\n`)
+}
+
+function toolResult(id, text, isError = false) {
+  result(id, { content: [{ type: 'text', text }], ...(isError ? { isError: true } : {}) })
+}
+
+function handle(message) {
+  if (!message || message.jsonrpc !== '2.0') return
+  if (message.method === 'initialize') {
+    result(message.id, {
+      protocolVersion: message.params?.protocolVersion ?? '2025-06-18',
+      capabilities: { tools: { listChanged: false } },
+      serverInfo: { name: 'open-mercato-agent-harness', version: '1.0.0' },
+    })
+    return
+  }
+  if (message.method === 'ping') { result(message.id, {}); return }
+  if (message.method === 'tools/list') { result(message.id, { tools }); return }
+  if (message.method !== 'tools/call') return
+  try {
+    const name = message.params?.name
+    const input = message.params?.arguments ?? {}
+    if (name === 'read') {
+      if (input.reason !== undefined && !INSTALLED_FALLBACK_REASON_CODES.has(input.reason)) {
+        throw new Error('read reason must be a declared installed-source fallback reason code')
+      }
+      if (input.capabilityId !== undefined
+        && (typeof input.capabilityId !== 'string' || !/^[a-z0-9][a-z0-9.-]{0,63}$/.test(input.capabilityId))) {
+        throw new Error('read capabilityId must be a bounded surface-inventory capability id')
+      }
+      const { real } = resolveRead(input.path)
+      toolResult(message.id, fs.readFileSync(real, 'utf8'))
+      return
+    }
+    if (name === 'write') {
+      if (typeof input.content !== 'string' || Buffer.byteLength(input.content) > MAX_WRITE_BYTES) throw new Error('content must be a bounded string')
+      const target = resolveWrite(input.path)
+      const temporary = `${target}.om-harness-${process.pid}.tmp`
+      fs.writeFileSync(temporary, input.content, { encoding: 'utf8', mode: 0o600, flag: 'wx' })
+      fs.renameSync(temporary, target)
+      toolResult(message.id, `wrote ${input.path}`)
+      return
+    }
+    throw new Error('unknown tool')
+  } catch (error) {
+    toolResult(message.id, error instanceof Error ? error.message : String(error), true)
+  }
+}
+
+let buffer = ''
+process.stdin.setEncoding('utf8')
+process.stdin.on('data', (chunk) => {
+  buffer += chunk
+  while (true) {
+    const newline = buffer.indexOf('\n')
+    if (newline < 0) break
+    const line = buffer.slice(0, newline).replace(/\r$/, '')
+    buffer = buffer.slice(newline + 1)
+    if (!line.trim()) continue
+    try { handle(JSON.parse(line)) } catch (error) {
+      process.stderr.write(`agent-harness-tool-server: invalid request: ${error instanceof Error ? error.message : String(error)}\n`)
+    }
+  }
+})

package/dist/agentic/shared/scripts/check-lessons.mjs

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+export const LESSON_AREAS = new Set([
+  'architecture',
+  'module-data',
+  'umes',
+  'backend-ui',
+  'integration',
+  'ai-workflow',
+  'debugging',
+  'testing',
+  'framework-context',
+  'spec-pr',
+])
+
+const INDEX_MAX_BYTES = 30 * 1024
+const RECORD_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*\.md$/
+const MODULE_PATTERN = /^[a-z0-9]+(?:_[a-z0-9]+)*$/
+const TOPIC_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+const INDEX_ROW_PATTERN = /^- \[(.+)]\(lessons\/([a-z0-9-]+\.md)\) — area:([^;]+); module:([^;]+); topic:(.+)$/
+
+function parseFrontMatter(source, relativePath, errors) {
+  const match = source.match(/^---\n([\s\S]*?)\n---\n\n# (.+)\n/)
+  if (!match) {
+    errors.push(`${relativePath}: expected JSON-valued front matter followed by one H1`)
+    return null
+  }
+
+  const metadata = {}
+  for (const line of match[1].split('\n')) {
+    const separator = line.indexOf(':')
+    if (separator < 1) {
+      errors.push(`${relativePath}: malformed front matter line ${JSON.stringify(line)}`)
+      continue
+    }
+    const key = line.slice(0, separator)
+    try {
+      metadata[key] = JSON.parse(line.slice(separator + 1).trim())
+    } catch {
+      errors.push(`${relativePath}: ${key} must use valid JSON syntax`)
+    }
+  }
+
+  const expectedKeys = ['title', 'modules', 'areas', 'topics']
+  const actualKeys = Object.keys(metadata).sort()
+  if (JSON.stringify(actualKeys) !== JSON.stringify([...expectedKeys].sort())) {
+    errors.push(`${relativePath}: front matter keys must be exactly ${expectedKeys.join(', ')}`)
+  }
+  if (typeof metadata.title !== 'string' || metadata.title.length === 0) {
+    errors.push(`${relativePath}: title must be a non-empty string`)
+  } else if (metadata.title !== match[2]) {
+    errors.push(`${relativePath}: front matter title must match the H1`)
+  }
+
+  for (const key of ['modules', 'areas', 'topics']) {
+    if (!Array.isArray(metadata[key])) errors.push(`${relativePath}: ${key} must be an array`)
+  }
+  if (!Array.isArray(metadata.modules) || metadata.modules.length === 0) {
+    errors.push(`${relativePath}: modules must contain an owning module/package or platform`)
+  } else if (metadata.modules.some((value) => typeof value !== 'string' || !MODULE_PATTERN.test(value))) {
+    errors.push(`${relativePath}: modules must use lowercase snake_case tags`)
+  }
+  if (!Array.isArray(metadata.areas) || metadata.areas.length === 0) {
+    errors.push(`${relativePath}: areas must contain at least one standalone router area`)
+  } else if (metadata.areas.some((value) => !LESSON_AREAS.has(value))) {
+    errors.push(`${relativePath}: areas contain a value outside the standalone router taxonomy`)
+  }
+  if (!Array.isArray(metadata.topics) || metadata.topics.length < 2 || metadata.topics.length > 6) {
+    errors.push(`${relativePath}: topics must contain between two and six important concepts`)
+  } else if (metadata.topics.some((value) => typeof value !== 'string' || !TOPIC_PATTERN.test(value))) {
+    errors.push(`${relativePath}: topics must use lowercase kebab-case tags`)
+  }
+
+  for (const key of ['modules', 'areas', 'topics']) {
+    if (Array.isArray(metadata[key]) && new Set(metadata[key]).size !== metadata[key].length) {
+      errors.push(`${relativePath}: ${key} must not contain duplicates`)
+    }
+  }
+
+  return metadata
+}
+
+export function checkLessonsCatalog(rootDir) {
+  const errors = []
+  const indexPath = path.join(rootDir, '.ai', 'lessons.md')
+  const lessonsDir = path.join(rootDir, '.ai', 'lessons')
+  if (!fs.existsSync(indexPath)) return [`${indexPath}: lesson index is missing`]
+
+  const indexSource = fs.readFileSync(indexPath, 'utf8')
+  const indexBytes = Buffer.byteLength(indexSource)
+  if (indexBytes > INDEX_MAX_BYTES) {
+    errors.push(`.ai/lessons.md: ${indexBytes} bytes exceeds the ${INDEX_MAX_BYTES}-byte progressive-loading budget`)
+  }
+  if (/\*\*(?:Context|Problem|Rule|Applies to)\*\*:/.test(indexSource)) {
+    errors.push('.ai/lessons.md: full lesson prose belongs in .ai/lessons/, not the catalog')
+  }
+
+  const recordNames = fs.existsSync(lessonsDir)
+    ? fs.readdirSync(lessonsDir, { withFileTypes: true })
+      .filter((entry) => entry.isFile() && entry.name.endsWith('.md') && !entry.name.startsWith('_'))
+      .map((entry) => entry.name)
+      .sort()
+    : []
+  const records = new Map()
+  const titles = new Set()
+  for (const fileName of recordNames) {
+    const relativePath = `.ai/lessons/${fileName}`
+    if (!RECORD_NAME_PATTERN.test(fileName)) errors.push(`${relativePath}: filename must use kebab-case`)
+    const metadata = parseFrontMatter(fs.readFileSync(path.join(lessonsDir, fileName), 'utf8'), relativePath, errors)
+    if (!metadata) continue
+    if (titles.has(metadata.title)) errors.push(`${relativePath}: duplicate lesson title ${JSON.stringify(metadata.title)}`)
+    titles.add(metadata.title)
+    records.set(fileName, metadata)
+  }
+
+  const indexed = new Set()
+  for (const line of indexSource.split('\n')) {
+    if (!line.startsWith('- [')) continue
+    const match = line.match(INDEX_ROW_PATTERN)
+    if (!match) {
+      errors.push(`.ai/lessons.md: malformed catalog row ${JSON.stringify(line)}`)
+      continue
+    }
+    const [, title, fileName, areaText, moduleText, topicText] = match
+    if (indexed.has(fileName)) errors.push(`.ai/lessons.md: duplicate link to lessons/${fileName}`)
+    indexed.add(fileName)
+    const metadata = records.get(fileName)
+    if (!metadata) {
+      errors.push(`.ai/lessons.md: lessons/${fileName} does not exist`)
+      continue
+    }
+    const indexedMetadata = {
+      title,
+      areas: areaText.split(','),
+      modules: moduleText.split(','),
+      topics: topicText.split(','),
+    }
+    for (const key of ['title', 'areas', 'modules', 'topics']) {
+      if (JSON.stringify(indexedMetadata[key]) !== JSON.stringify(metadata[key])) {
+        errors.push(`.ai/lessons.md: ${key} drift for lessons/${fileName}`)
+      }
+    }
+  }
+
+  for (const fileName of records.keys()) {
+    if (!indexed.has(fileName)) errors.push(`.ai/lessons/${fileName}: record is missing from the catalog`)
+  }
+  const declaredCount = indexSource.match(/catalog indexes (\d+) focused lessons/)
+  if (!declaredCount || Number(declaredCount[1]) !== records.size) {
+    errors.push(`.ai/lessons.md: declared lesson count must equal ${records.size}`)
+  }
+
+  return errors
+}
+
+function parseRoot(args) {
+  if (args.length === 0) return process.cwd()
+  if (args.length === 2 && args[0] === '--root') return path.resolve(args[1])
+  throw new Error('Usage: check-lessons.mjs [--root <app-root>]')
+}
+
+export function main(args = process.argv.slice(2)) {
+  const rootDir = parseRoot(args)
+  const errors = checkLessonsCatalog(rootDir)
+  if (errors.length > 0) {
+    for (const error of errors) console.error(`- ${error}`)
+    process.exitCode = 1
+    return
+  }
+  console.log(`Lessons catalog is valid: ${rootDir}`)
+}
+
+const entryPath = process.argv[1] ? pathToFileURL(path.resolve(process.argv[1])).href : null
+if (entryPath === import.meta.url) main()