@jc_stack/ez-agents 0.1.0-beta.13 → 0.1.0-beta.19

package/docs/workforce-watch.md

@@ -0,0 +1,101 @@
+# Workforce Watch
+
+Workforce Watch is a separate, small Docker service for missed agent check-ins
+and explicit terminal failures. It is not an agent, scheduler, log store or
+remote-execution channel. It retains only the five latest compact activity
+records supplied by each enrolled worker.
+
+Run it in a failure domain separate from the workers it watches. In particular,
+it must not rely on the Stocks VM to report a Stocks VM outage, and a separate
+host is required to detect a Mac-wide outage.
+
+## Start the monitor
+
+Set private monitor-only values, never agent-workspace or source-control values:
+
+```text
+EZ_WATCH_ENROLL_TOKEN=<private fleet enrollment secret>
+EZ_WATCH_PAGERDUTY_SECRET_FILE=/absolute/path/to/a-0600-workforce-pagerduty-key
+TELEGRAM_BOT_TOKEN=<alert bot token>
+EZ_WATCH_TELEGRAM_CHAT_ID=<owner chat id>
+```
+
+PagerDuty is the fleet incident owner. Workforce Watch sends a `trigger` for
+each missed check-in or terminal failure, then a `resolve` with the stable
+deduplication key `ez:workforce:<worker-id>` after sustained recovery. Use one
+approved Events API v2 routing key for the fleet; it may be the existing
+PagerDuty integration when that is the desired escalation policy. Never put it
+in a worker's environment. The secret file contains only that key, is mode
+`0600`, and is mounted as `/run/secrets/workforce_watch_pagerduty`; it is never
+a Compose or container environment value. Telegram is optional, supplementary
+owner visibility. PagerDuty is required: a Watch deployment without its
+routing-key secret fails closed rather than silently running without paging.
+
+The owner may explicitly authorize the CTO bot token temporarily. A dedicated
+alert bot remains preferable because it preserves an independent delivery identity.
+
+```sh
+docker compose -f compose.workforce-watch.yaml up -d --build
+curl http://127.0.0.1:9919/healthz
+```
+
+The default bind is loopback. Put private TLS networking or a private reverse
+proxy in front of it before remote workers use it; do not expose enrollment or
+check-in traffic publicly.
+
+## Enroll and check in
+
+The worker selects its monitor through its configured URL. It submits the fleet
+enrollment secret once; the response contains the worker-specific secret. Store
+that response only in the worker's private service environment and discard it
+from shell history and logs.
+
+```sh
+curl --fail-with-body -X POST "$EZ_WATCH_URL/v1/enroll" \
+  -H "Authorization: Bearer $EZ_WATCH_ENROLL_TOKEN" \
+  -H 'content-type: application/json' \
+  --data '{"workerId":"stocks-production","checkInSeconds":300,"graceSeconds":180,"severity":"critical"}'
+```
+
+The supervisor, not the LLM, posts check-ins using the returned worker secret:
+
+```sh
+curl --fail-with-body -X POST "$EZ_WATCH_URL/v1/workers/stocks-production/check-in" \
+  -H "Authorization: Bearer $EZ_WATCH_WORKER_TOKEN" \
+  -H 'content-type: application/json' \
+  --data '{"status":"ok","activity":"strategy receipt delivered","runId":"daily-strategy-2026-09-11"}'
+```
+
+An unrecoverable condition sends `{"status":"failed","terminal":true,...}`.
+Optional `activity`, `error`, `runId`, and `logsHint` fields are size-limited and
+appear in an alert. They must be public-safe operational context, never stdout,
+prompts, holdings, credentials, or provider payloads.
+
+## Inspect
+
+The enrollment token reads redacted state; worker secrets never appear:
+
+```sh
+curl --fail-with-body "$EZ_WATCH_URL/v1/workers" \
+  -H "Authorization: Bearer $EZ_WATCH_ENROLL_TOKEN"
+```
+
+For host replacement or a suspected worker-secret exposure, rotate that worker's
+secret with the enrollment token. The old secret stops working immediately:
+
+```sh
+curl --fail-with-body -X POST "$EZ_WATCH_URL/v1/workers/stocks-production/rotate" \
+  -H "Authorization: Bearer $EZ_WATCH_ENROLL_TOKEN"
+```
+
+Store the returned worker secret in the replacement supervisor before stopping
+the prior one.
+
+The service triggers once for a missed deadline or terminal failure. It sends a
+recovery notice only after two clean check-ins by default to prevent flapping.
+
+If a worker fails again during a partially delivered recovery, channels that
+already accepted recovery receive a fresh trigger. Channels still open retain
+their delivery state, so they do not receive duplicate opening alerts. This
+applies to terminal failures, failed check-ins, and missed check-ins, including
+after a Watch restart.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jc_stack/ez-agents",
-  "version": "0.1.0-beta.13",
+  "version": "0.1.0-beta.19",
   "private": false,
   "type": "module",
   "description": "A lightweight foundation for persistent business AI assistants using existing AI harnesses, workspaces and plugins.",
@@ -20,7 +20,8 @@
     "ezenciel-agents-create": "bin/ezenciel-agents-create",
     "ezenciel-agents-host": "bin/ezenciel-agents-host",
     "ezenciel-agents-tools": "bin/ezenciel-agents-tools.mjs",
-    "ezenciel-agents-ai": "bin/ezenciel-agents-ai.mjs"
+    "ezenciel-agents-ai": "bin/ezenciel-agents-ai.mjs",
+    "ezenciel-agents-watch": "bin/ezenciel-agents-watch.mjs"
   },
   "files": [
     "default-plugins.json",
@@ -35,6 +36,7 @@
     "CONTRIBUTING.md",
     "Dockerfile",
     "compose.yaml",
+    "compose.workforce-watch.yaml",
     "docker",
     "compose.whatsapp.yaml",
     "scripts/smoke.ts",
@@ -47,11 +49,14 @@
     "test",
     "tsconfig.json",
     "scripts/assert-local-registry.mjs",
-    ".dockerignore"
+    ".dockerignore",
+    "scripts/trusted-beta.mjs",
+    "scripts/generate-publish-caller.mjs",
+    "scripts/smoke-busy-reply.ts"
   ],
   "publishConfig": {
     "access": "public",
-    "tag": "beta"
+    "tag": "latest"
   },
   "scripts": {
     "setup": "tsx --env-file-if-exists=.env src/setup.ts",

package/scripts/generate-publish-caller.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+// Print a reviewed caller. Does not write repositories or enroll npm trust.
+import assert from 'node:assert/strict';
+import { pathToFileURL } from 'node:url';
+
+export function generateCaller({ repository, packageName, publisherSha, checks }) {
+  assert.match(repository, /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/, 'Invalid repository');
+  assert.match(packageName, /^@[a-z0-9_-]+\/[a-z0-9_.-]+$/, 'Expected scoped npm package');
+  assert.match(publisherSha, /^[a-f0-9]{40}$/, 'Pin the reviewed shared publisher to a full commit SHA');
+  assert(Array.isArray(checks) && checks.length > 0 && checks.every(c => typeof c === 'string' && /^[A-Za-z0-9 (),_.-]+$/.test(c)), 'Required CI check names are mandatory');
+  const core = repository === 'jdorado/ez-agents';
+  const reference = core ? './.github/workflows/npm-beta-shared.yml' : `jdorado/ez-agents/.github/workflows/npm-beta-shared.yml@${publisherSha}`;
+  return `# Generated by scripts/generate-publish-caller.mjs; review changes before merging.
+name: Publish verified npm beta
+on:
+  workflow_dispatch:
+    inputs:
+      release-id:
+        description: 'Numeric ID of the staged draft prerelease'
+        required: true
+        type: string
+      version:
+        description: 'Reviewed beta version staged as draft release vVERSION'
+        required: true
+        type: string
+      source-sha:
+        description: 'Full tested commit SHA; must be current main'
+        required: true
+        type: string
+      artifact-sha256:
+        description: 'SHA-256 of the exact independently verified candidate.tgz'
+        required: true
+        type: string
+permissions: {}
+jobs:
+  publish:
+    if: github.repository == '${repository}' && github.ref == 'refs/heads/main'
+    permissions:
+      contents: write
+      checks: read
+      actions: read
+      pull-requests: read
+      id-token: write
+    uses: ${reference}
+    with:
+      package: '${packageName}'
+      publisher-sha: ${core ? '${{ github.sha }}' : `'${publisherSha}'`}
+      required-checks: '${JSON.stringify(checks)}'
+      release-id: \${{ inputs.release-id }}
+      version: \${{ inputs.version }}
+      source-sha: \${{ inputs.source-sha }}
+      artifact-sha256: \${{ inputs.artifact-sha256 }}
+`;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const [repository, packageName, publisherSha, checksJson, ...extra] = process.argv.slice(2);
+  if (!checksJson || extra.length) throw new Error('Usage: node scripts/generate-publish-caller.mjs OWNER/REPO @SCOPE/PACKAGE SHARED_COMMIT_SHA \'["required CI name"]\'');
+  process.stdout.write(generateCaller({ repository, packageName, publisherSha, checks: JSON.parse(checksJson) }));
+}

package/scripts/smoke-busy-reply.ts

@@ -0,0 +1,58 @@
+// Real restricted Codex reply while a synthetic writer stays active. No Telegram network.
+import { mkdtemp, mkdir, writeFile, symlink } from 'node:fs/promises'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { spawn } from 'node:child_process'
+import { createRelay } from '../src/index.js'
+import { RunStore } from '../src/runs.js'
+import { ControlStore } from '../src/control-state.js'
+import { initialPreset } from '../src/ai.js'
+import { startExecutorJob } from '../src/executor.js'
+import { serveHostExecutor } from '../src/host-executor.js'
+import { fileURLToPath } from 'node:url'
+import { initializeWorkspace } from '../src/workspace.js'
+import type { Update } from 'grammy/types'
+if (process.argv.includes('--host')) {
+ const root=process.argv[process.argv.indexOf('--host')+1], abort=new AbortController()
+ process.once('SIGTERM',()=>abort.abort())
+ await serveHostExecutor({cli:'codex',agents:[{name:'fixture',workspace:join(root,'mind'),controlDir:join(root,'control'),binDir:fileURLToPath(new URL('../bin',import.meta.url)),sharedWorkspace:join(root,'mind')}]},abort.signal,async(texts,options)=>{
+  if((await new RunStore(options.controlDir).get(options.runId))?.replyOnly)return startExecutorJob(texts,options)
+  const child=spawn(process.execPath,['-e','setInterval(()=>{},1000)'],{detached:true,stdio:['pipe','pipe','pipe']})
+  return {child,stdout:'',cleanup:async()=>{}}
+ })
+ process.exit(0)
+}
+const root=await mkdtemp(join(tmpdir(),'ez-busy-reply-')), workspace=join(root,'mind'), controlDir=join(root,'control')
+await initializeWorkspace(workspace);await mkdir(controlDir,{recursive:true})
+if(process.env.EZ_REPLY_QA_AUTH){await mkdir(join(controlDir,'cli','codex'),{recursive:true});await symlink(process.env.EZ_REPLY_QA_AUTH,join(controlDir,'cli','codex','auth.json'))}
+const hostMode=process.argv.includes('--transport')
+const hostEnvironment={...process.env};delete hostEnvironment.EZ_EXECUTOR_TRANSPORT
+const host=hostMode?spawn(process.execPath,['--import',fileURLToPath(new URL('../node_modules/tsx/dist/loader.mjs',import.meta.url)),fileURLToPath(import.meta.url),'--host',root],{env:hostEnvironment,stdio:['ignore','inherit','inherit']}):undefined
+if(hostMode)process.env.EZ_EXECUTOR_TRANSPORT='host'
+const control=new ControlStore(controlDir,1000),runs=new RunStore(controlDir)
+await control.requestPairing(101,101);await control.approveOwner(101)
+let writer:any,replyEvents=''
+const relay=createRelay({workspace,controlDir,pairingTtlMs:1000,executorTimeoutMs:0,executorCli:'codex',telegramBotToken:'fixture'},async(texts,options)=>{
+ if(hostMode)return startExecutorJob(texts,options)
+ const run=await runs.get(options.runId)
+ if(run?.replyOnly){const job=await startExecutorJob(texts,options);job.child.stdout?.on('data',c=>{replyEvents+=c});return job}
+ const child=spawn(process.execPath,['-e','setInterval(()=>{},1000)'],{stdio:['pipe','pipe','pipe']});writer=child
+ return {child,stdout:'',cleanup:async()=>{}}
+})
+relay.bot.botInfo={id:999,is_bot:true,first_name:'Fixture',username:'fixture_bot'} as any
+const replies:string[]=[]
+relay.bot.api.config.use(async(_p,method,payload)=>{if(method==='sendMessage')replies.push((payload as any).text);return {ok:true,result:method==='sendMessage'?{message_id:replies.length,date:0,chat:{id:101,type:'private'},text:(payload as any).text}:true} as any})
+const msg=(id:number,text:string):Update=>({update_id:id,message:{message_id:id,date:0,text,from:{id:101,is_bot:false,first_name:'Fixture'},chat:{id:101,type:'private',first_name:'Fixture'}}})
+try{
+ await relay.bot.handleUpdate(msg(1,'Long work'));await relay.drainInbox(true)
+ await relay.bot.handleUpdate(msg(2,'What is running? Also calculate 17 times 19. Use your available reply tools. Do not queue any work.'));await relay.drainInbox(true)
+ const started=Date.now()
+ while(!replies.length && Date.now()-started<120000){await relay.drainOutbox();await new Promise(r=>setTimeout(r,250))}
+ if(!replies.some(s=>s.includes('323')))throw new Error('No verified arithmetic reply: '+JSON.stringify(replies))
+ if((await runs.get('tg_1'))?.status!=='running')throw new Error('Writer stopped')
+ while((await runs.get('tg_2'))?.status==='running' && Date.now()-started<120000)await new Promise(r=>setTimeout(r,250))
+ if((await runs.get('tg_2'))?.status!=='completed')throw new Error('Reply did not finish successfully')
+ const reply=await runs.get('tg_2');if(!reply?.replyOnly)throw new Error('No restricted reply lane')
+ await writeFile(join(root,'evidence.json'),JSON.stringify({replyMs:Date.now()-started,replies,writerRunning:(await runs.get('tg_1'))?.status==='running',replyEvents},null,2))
+ console.log(JSON.stringify({root,replyMs:Date.now()-started,replies,writerRunning:true}))
+}finally{await relay.stop();writer?.kill();host?.kill();delete process.env.EZ_EXECUTOR_TRANSPORT}

package/scripts/trusted-beta.mjs

@@ -0,0 +1,289 @@
+#!/usr/bin/env node
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { mkdir, readFile, writeFile, mkdtemp, rm, rename } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { resolve, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isDeepStrictEqual } from 'node:util';
+
+const REGISTRY = 'https://registry.npmjs.org/';
+const CORE = 'jdorado/ez-agents';
+const MAX_ARTIFACT = 100 * 1024 * 1024;
+const assert = (condition, message) => { if (!condition) throw new Error(message); };
+export const sha256 = bytes => createHash('sha256').update(bytes).digest('hex');
+
+export function publishEnvironment(env) {
+  const allowed = ['PATH', 'HOME', 'TMPDIR', 'TEMP', 'TMP', 'LANG', 'LC_ALL', 'CI',
+    'GITHUB_ACTIONS', 'GITHUB_WORKFLOW', 'GITHUB_WORKFLOW_REF', 'GITHUB_WORKFLOW_SHA',
+    'GITHUB_REPOSITORY', 'GITHUB_REPOSITORY_ID', 'GITHUB_REPOSITORY_OWNER', 'GITHUB_REPOSITORY_OWNER_ID',
+    'GITHUB_SERVER_URL', 'GITHUB_REF', 'GITHUB_REF_NAME', 'GITHUB_REF_TYPE', 'GITHUB_SHA',
+    'GITHUB_RUN_ID', 'GITHUB_RUN_NUMBER', 'GITHUB_RUN_ATTEMPT', 'GITHUB_EVENT_NAME', 'GITHUB_JOB',
+    'GITHUB_ACTOR', 'GITHUB_ACTOR_ID', 'RUNNER_ENVIRONMENT', 'RUNNER_OS', 'RUNNER_ARCH',
+    'ACTIONS_ID_TOKEN_REQUEST_URL', 'ACTIONS_ID_TOKEN_REQUEST_TOKEN'];
+  return Object.fromEntries(allowed.filter(key => env[key] !== undefined).map(key => [key, env[key]]));
+}
+
+export function publishArguments(path, npmrc, globalNpmrc) {
+  return ['publish', path, '--fetch-retries=0', '--ignore-scripts', '--provenance', '--access', 'public', '--tag', 'latest', '--registry', REGISTRY, '--userconfig', npmrc, '--globalconfig', globalNpmrc];
+}
+
+export function identity(env) {
+  const value = { repository: env.RELEASE_REPOSITORY, package: env.RELEASE_PACKAGE,
+    version: env.RELEASE_VERSION, sourceSha: env.RELEASE_SOURCE_SHA,
+    sha256: env.RELEASE_SHA256, releaseId: Number(env.RELEASE_ID), requiredChecks: JSON.parse(env.RELEASE_REQUIRED_CHECKS || 'null') };
+  assert(/^[1-9]\d*$/.test(env.RELEASE_ID || '') && Number.isSafeInteger(value.releaseId), 'Invalid draft release ID');
+  assert(/^jdorado\/[A-Za-z0-9_.-]+$/.test(value.repository || ''), 'Invalid repository');
+  assert(/^@jc_stack\/[a-z0-9-]+$/.test(value.package || ''), 'Invalid package');
+  assert(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)-beta\.(0|[1-9]\d*)$/.test(value.version || ''), 'Only immutable beta.N versions are allowed');
+  assert(/^[a-f0-9]{40}$/.test(value.sourceSha || ''), 'Invalid source SHA');
+  assert(/^[a-f0-9]{64}$/.test(value.sha256 || ''), 'Invalid artifact SHA256');
+  assert(Array.isArray(value.requiredChecks) && value.requiredChecks.length > 0 && value.requiredChecks.every(x => typeof x === 'string' && x.length > 0) && new Set(value.requiredChecks).size === value.requiredChecks.length, 'Required checks must be a nonempty unique list');
+  assert(env.GITHUB_REPOSITORY === value.repository, 'Caller repository mismatch');
+  assert(env.GITHUB_EVENT_NAME === 'workflow_dispatch' && env.GITHUB_REF === 'refs/heads/main', 'Must manually dispatch from main');
+  assert(env.GITHUB_SHA === value.sourceSha, 'Source must equal dispatched source');
+  return value;
+}
+
+export function validateManifest(manifest, expected) {
+  assert(manifest.name === expected.package && manifest.version === expected.version, 'Package identity mismatch');
+  assert(manifest.private !== true, 'Private packages cannot be published');
+  const repo = typeof manifest.repository === 'string' ? manifest.repository : manifest.repository?.url;
+  assert(repo === `git+https://github.com/${expected.repository}.git` || repo === `https://github.com/${expected.repository}.git` || repo === `https://github.com/${expected.repository}`, 'Package repository mismatch');
+  const config = manifest.publishConfig || {};
+  assert(Object.keys(config).every(key => ['access', 'tag', 'registry', 'provenance'].includes(key)), 'Unsupported publish configuration');
+  assert(config.access === undefined || config.access === 'public', 'Invalid publish access');
+  assert(config.tag === undefined || config.tag === 'latest', 'Invalid publish tag');
+  assert(config.registry === undefined || config.registry === REGISTRY || config.registry === REGISTRY.slice(0, -1), 'Invalid publish registry');
+  assert(config.provenance !== false, 'Provenance must not be disabled');
+}
+
+export function validateReceipt(receipt, expected) {
+  for (const key of ['repository', 'package', 'version', 'sourceSha', 'sha256']) {
+    assert(receipt[key] === expected[key], `Receipt ${key} mismatch`);
+  }
+  const base = `https://github.com/${expected.repository}/`;
+  assert(typeof receipt.independentReviewUrl === 'string' && receipt.independentReviewUrl.startsWith(base) && /^pull\/[1-9]\d*(?:#[A-Za-z0-9_-]+)?$/.test(receipt.independentReviewUrl.slice(base.length)), 'Missing independent review PR URL');
+  assert(Array.isArray(receipt.testEvidenceUrls) && receipt.testEvidenceUrls.length > 0 && receipt.testEvidenceUrls.every(url => typeof url === 'string' && url.startsWith(base) && /^(?:actions\/runs|pull|issues)\/[1-9]\d*(?:#[A-Za-z0-9_-]+)?$/.test(url.slice(base.length))), 'Missing test evidence URLs');
+}
+
+export function validateChecks(checks, expected) {
+  const selected = [];
+  for (const name of expected.requiredChecks) {
+    const runs = checks.filter(check => check.name === name && check.head_sha === expected.sourceSha && check.app?.id === 15368).sort((a, b) => b.id - a.id);
+    assert(runs.length > 0 && runs[0].status === 'completed' && runs[0].conclusion === 'success', `Required GitHub Actions check not successful: ${name}`);
+    selected.push(runs[0]);
+  }
+  return selected;
+}
+
+export function tarManifest(path) {
+  const options = { encoding: 'utf8', maxBuffer: 8 * 1024 * 1024, timeout: 30_000 };
+  const entries = execFileSync('tar', ['-tzf', path], options).trim().split('\n');
+  assert(entries.filter(name => name === 'package/package.json').length === 1, 'Tarball must have exactly one package/package.json');
+  assert(entries.every(name => name.startsWith('package/') && !name.split('/').includes('..') && !name.includes('\\')), 'Unsafe tarball path');
+  const details = execFileSync('tar', ['-tvzf', path], options).trim().split('\n');
+  assert(details.every(line => line.startsWith('-') || line.startsWith('d')), 'Tarball links or special files are forbidden');
+  return JSON.parse(execFileSync('tar', ['-xOf', path, 'package/package.json'], { ...options, maxBuffer: 1024 * 1024 }));
+}
+
+async function responseBytes(response, max = MAX_ARTIFACT) {
+  assert(response.ok, `HTTP ${response.status} while reading release evidence`);
+  assert(Number(response.headers.get('content-length') || 0) <= max, 'Response too large');
+  let size = 0; const chunks = [];
+  for await (const chunk of response.body) { size += chunk.length; assert(size <= max, 'Response too large'); chunks.push(chunk); }
+  return Buffer.concat(chunks);
+}
+
+export function githubClient(token, fetcher = fetch) {
+  return async (path, binary = false) => {
+    assert(path.startsWith('/repos/'), 'Invalid GitHub API path');
+    const response = await fetcher(`https://api.github.com${path}`, {
+      headers: { Accept: binary ? 'application/octet-stream' : 'application/vnd.github+json', ...(token ? { Authorization: `Bearer ${token}` } : {}), 'X-GitHub-Api-Version': '2022-11-28' },
+      redirect: 'manual', signal: AbortSignal.timeout(30_000),
+    });
+    if (binary && [301, 302, 303, 307, 308].includes(response.status)) {
+      const location = new URL(response.headers.get('location'));
+      assert(location.protocol === 'https:' && (location.hostname === 'release-assets.githubusercontent.com' || location.hostname === 'objects.githubusercontent.com'), 'Unexpected asset redirect');
+      return responseBytes(await fetcher(location, { signal: AbortSignal.timeout(60_000), redirect: 'error' }));
+    }
+    const bytes = await responseBytes(response, binary ? MAX_ARTIFACT : 8 * 1024 * 1024);
+    return binary ? bytes : JSON.parse(bytes.toString());
+  };
+}
+
+export async function validateSource(expected, api) {
+  const repo = await api(`/repos/${expected.repository}`);
+  assert(repo.full_name === expected.repository && repo.private === false && repo.visibility === 'public' && repo.default_branch === 'main' && !repo.archived, 'Repository must be public and active on main');
+  const catalog = await api(`/repos/${CORE}/contents/docs/plugin-catalog.md?ref=main`);
+  const catalogText = Buffer.from(catalog.content, 'base64').toString('utf8');
+  const enrolled = catalogText.split('\n').some(line => line.startsWith('|') && line.includes(`](https://github.com/${expected.repository})`) && line.includes('`' + expected.package + '`'));
+  assert(expected.repository === CORE ? expected.package === '@jc_stack/ez-agents' : enrolled, 'Repository/package is not enrolled in public catalog');
+  const main = await api(`/repos/${expected.repository}/git/ref/heads/main`);
+  assert(main.object?.sha === expected.sourceSha, 'Source is no longer current main');
+  const manifest = await api(`/repos/${expected.repository}/contents/package.json?ref=${expected.sourceSha}`);
+  const sourceManifest = JSON.parse(Buffer.from(manifest.content, 'base64').toString('utf8'));
+  validateManifest(sourceManifest, expected);
+  let tag = (await api(`/repos/${expected.repository}/git/ref/tags/v${expected.version}`)).object;
+  for (let depth = 0; tag?.type === 'tag' && depth < 5; depth++) tag = (await api(`/repos/${expected.repository}/git/tags/${tag.sha}`)).object;
+  assert(tag?.type === 'commit' && tag.sha === expected.sourceSha, 'Release tag does not identify approved source');
+  // Select CI identity before considering outcomes: tag/PR runs at the same SHA
+  // must neither shadow main CI nor let a failed latest main run fall back.
+  const runs = [];
+  for (let page = 1; ; page++) {
+    assert(page <= 100, 'Too many workflow run pages');
+    const result = await api(`/repos/${expected.repository}/actions/workflows/ci.yml/runs?branch=main&event=push&head_sha=${expected.sourceSha}&per_page=100&page=${page}`);
+    assert(Array.isArray(result.workflow_runs), 'Invalid workflow run response');
+    runs.push(...result.workflow_runs.filter(run => run.head_sha === expected.sourceSha && run.event === 'push' && run.head_branch === 'main' && run.path === '.github/workflows/ci.yml'));
+    if (result.workflow_runs.length < 100) break;
+  }
+  const run = runs.sort((a, b) => b.id - a.id)[0];
+  assert(run && Number.isSafeInteger(run.id) && run.id > 0 && Number.isSafeInteger(run.run_attempt) && run.run_attempt > 0 && run.status === 'completed' && run.conclusion === 'success', 'Required check is not successful main push CI');
+  const jobs = [];
+  for (let page = 1; ; page++) {
+    assert(page <= 100, 'Too many job pages');
+    const result = await api(`/repos/${expected.repository}/actions/runs/${run.id}/attempts/${run.run_attempt}/jobs?per_page=100&page=${page}`);
+    assert(Array.isArray(result.jobs), 'Invalid job response');
+    jobs.push(...result.jobs);
+    if (result.jobs.length < 100) break;
+  }
+  const checks = [];
+  for (const name of expected.requiredChecks) {
+    const matches = jobs.filter(job => job.name === name);
+    assert(matches.length === 1, `Missing or ambiguous required CI job: ${name}`);
+    const job = matches[0];
+    assert(job.run_id === run.id && job.run_attempt === run.run_attempt && job.head_sha === expected.sourceSha && job.status === 'completed' && job.conclusion === 'success', `Required CI job not successful: ${name}`);
+    const prefix = `https://api.github.com/repos/${expected.repository}/check-runs/`;
+    assert(typeof job.check_run_url === 'string' && job.check_run_url.startsWith(prefix) && /^[1-9]\d*$/.test(job.check_run_url.slice(prefix.length)), 'Invalid job check evidence URL');
+    const check = await api(job.check_run_url.slice('https://api.github.com'.length));
+    assert(check.name === name && check.details_url === `https://github.com/${expected.repository}/actions/runs/${run.id}/job/${job.id}`, 'Check does not identify the required CI job');
+    checks.push(check);
+  }
+  validateChecks(checks, expected);
+  return sourceManifest;
+}
+
+export async function registryState(expected, fetcher = fetch) {
+  const response = await fetcher(`${REGISTRY}${encodeURIComponent(expected.package)}`, { signal: AbortSignal.timeout(30_000), redirect: 'error', headers: { Accept: 'application/json' } });
+  assert(response.status !== 404, 'Package does not exist: first reviewed beta needs interactive registry-owner publication before trust enrollment');
+  const data = JSON.parse((await responseBytes(response, 32 * 1024 * 1024)).toString());
+  assert(data.name === expected.package && data.versions && data['dist-tags'], 'Invalid registry package metadata');
+  const published = data.versions[expected.version];
+  if (!published) return { exists: false, latest: data['dist-tags'].latest ?? null, beta: data['dist-tags'].beta ?? null };
+  assert(published.name === expected.package && published.version === expected.version, 'Registry version identity mismatch');
+  const url = new URL(published.dist?.tarball);
+  assert(url.origin === REGISTRY.slice(0, -1), 'Unexpected registry tarball host');
+  const bytes = await responseBytes(await fetcher(url, { signal: AbortSignal.timeout(60_000), redirect: 'error' }));
+  assert(sha256(bytes) === expected.sha256, 'Existing registry artifact differs; never overwrite');
+  return { exists: true, latest: data['dist-tags'].latest ?? null, beta: data['dist-tags'].beta ?? null };
+}
+
+export async function validate(output, env = process.env, api = githubClient(env.GH_TOKEN)) {
+  const expected = identity(env);
+  const sourceManifest = await validateSource(expected, api);
+  const release = await api(`/repos/${expected.repository}/releases/${expected.releaseId}`);
+  assert(release.id === expected.releaseId && release.draft === true && release.prerelease === true && release.tag_name === `v${expected.version}`, 'Candidate must be a draft prerelease');
+  const asset = name => {
+    const matches = (release.assets || []).filter(item => item.name === name && item.state === 'uploaded');
+    assert(matches.length === 1 && Number.isSafeInteger(matches[0].id), `Missing or ambiguous asset: ${name}`);
+    return matches[0];
+  };
+  const candidateAsset = asset('candidate.tgz');
+  const receiptAsset = asset('release-receipt.json');
+  const bytes = await api(`/repos/${expected.repository}/releases/assets/${candidateAsset.id}`, true);
+  assert(sha256(bytes) === expected.sha256, 'Candidate artifact SHA256 mismatch');
+  const receipt = JSON.parse((await api(`/repos/${expected.repository}/releases/assets/${receiptAsset.id}`, true)).toString());
+  validateReceipt(receipt, expected);
+  // Dispatch is the authorized maintainer's attestation to these review/test URLs.
+  // Their existence alone is not an independent review verdict.
+  const reviewPr = Number(new URL(receipt.independentReviewUrl).pathname.split('/')[4]);
+  const pr = await api(`/repos/${expected.repository}/pulls/${reviewPr}`);
+  assert(pr.merged === true && pr.base?.repo?.full_name === expected.repository && pr.base?.ref === 'main' && pr.merge_commit_sha === expected.sourceSha, 'Review PR must be merged as the exact release source');
+  await mkdir(output, { recursive: true });
+  const tarball = resolve(output, 'candidate.tgz');
+  await writeFile(tarball, bytes, { flag: 'wx' });
+  const packedManifest = tarManifest(tarball);
+  validateManifest(packedManifest, expected);
+  assert(isDeepStrictEqual(packedManifest, sourceManifest), 'Packed manifest differs from approved source manifest');
+  await writeFile(resolve(output, 'validated.json'), JSON.stringify({ schema: 1, expected, receipt, releaseId: release.id, candidateAssetId: candidateAsset.id }, null, 2) + '\n', { flag: 'wx' });
+  return { sourceSha: expected.sourceSha, sha256: expected.sha256, version: expected.version };
+}
+
+export async function publishOnce(expected, { readState, publishTarball, sleep = ms => new Promise(resolve => setTimeout(resolve, ms)), report = console.log, record = async () => {}, allowWrite = true }) {
+  const before = await readState();
+  await record({ phase: 'preflight', before });
+  if (before.exists) {
+    assert(before.latest === expected.version, 'Artifact exists but latest tag differs; reconcile without republishing');
+    return { status: 'already-published', version: expected.version, sha256: expected.sha256 };
+  }
+  assert(allowWrite, 'Rerun cannot repeat publication: reconcile registry state and create a fresh authorized dispatch if a new attempt is needed');
+  await record({ phase: 'write-started', before });
+  let writeError;
+  try { await publishTarball(); } catch (error) { writeError = error; }
+  let lastError;
+  for (let attempt = 0; attempt < 4; attempt++) {
+    if (attempt) await sleep(5000);
+    try {
+      const after = await readState();
+      await record({ phase: 'readback', before, after, publishCommandFailed: Boolean(writeError), attempt });
+      if (after.exists && after.latest === expected.version) {
+        if (writeError) report('Publish command was uncertain; registry readback verified exact artifact and latest tag.');
+        return { status: 'published', version: expected.version, sha256: expected.sha256 };
+      }
+      lastError = new Error('Exact artifact and latest tag not yet verified');
+    } catch (error) { lastError = error; await record({ phase: 'readback-error', before, error: error.message, attempt }); }
+  }
+  throw new Error(`Publication unresolved; do not repeat the write before registry reconciliation: ${lastError?.message || writeError?.message}`);
+}
+
+export async function publish(output, env = process.env) {
+  const expected = identity(env);
+  const bundle = JSON.parse(await readFile(resolve(output, 'validated.json'), 'utf8'));
+  assert(bundle.schema === 1 && JSON.stringify(bundle.expected) === JSON.stringify(expected), 'Validated bundle does not match dispatched identity');
+  validateReceipt(bundle.receipt, expected);
+  const path = resolve(output, 'candidate.tgz');
+  assert(sha256(await readFile(path)) === expected.sha256, 'Validated artifact changed');
+  const packedManifest = tarManifest(path);
+  validateManifest(packedManifest, expected);
+  const sourceManifest = await validateSource(expected, githubClient(env.GH_TOKEN));
+  assert(isDeepStrictEqual(packedManifest, sourceManifest), 'Packed manifest differs from approved source manifest');
+  assert(!env.NODE_AUTH_TOKEN && !env.NPM_TOKEN, 'Token-based npm publishing is forbidden');
+  const temporary = await mkdtemp(join(tmpdir(), 'trusted-beta-'));
+  try {
+    const npmrc = join(temporary, 'npmrc');
+    const globalNpmrc = join(temporary, 'global-npmrc');
+    await writeFile(npmrc, 'registry=https://registry.npmjs.org/\n');
+    await writeFile(globalNpmrc, '');
+    const events = [];
+    const record = async event => {
+      events.push({ at: new Date().toISOString(), ...event });
+      const receiptPath = resolve(output, 'publication-receipt.json');
+      await writeFile(`${receiptPath}.${process.pid}.tmp`, JSON.stringify({ schema: 1, expected, events }, null, 2) + '\n', { mode: 0o600 });
+      await rename(`${receiptPath}.${process.pid}.tmp`, receiptPath);
+    };
+    try {
+      const result = await publishOnce(expected, {
+      record,
+      allowWrite: env.GITHUB_RUN_ATTEMPT === '1',
+      readState: () => registryState(expected),
+      publishTarball: () => execFileSync('npm', publishArguments(path, npmrc, globalNpmrc), {
+        cwd: temporary, stdio: 'inherit', timeout: 180_000,
+        env: publishEnvironment(env),
+      }),
+    });
+      await record({ phase: 'complete', result });
+      return result;
+    } catch (error) {
+      await record({ phase: 'failed', error: error.message });
+      throw error;
+    }
+  } finally { await rm(temporary, { recursive: true, force: true }); }
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const [mode, output] = process.argv.slice(2);
+    assert(['validate', 'publish'].includes(mode) && output && process.argv.length === 4, 'Usage: trusted-beta.mjs validate|publish OUTPUT_DIR');
+    console.log(JSON.stringify(await (mode === 'validate' ? validate(output) : publish(output))));
+  } catch (error) { console.error(error.message); process.exitCode = 1; }
+}

package/src/agent-guidance.ts

@@ -0,0 +1,9 @@
+import { readFileSync } from 'node:fs'
+
+// Resolve against the installed package, never the agent's editable workspace.
+export const agentGuidance = (): string =>
+  readFileSync(new URL('../templates/agent-guidance.md', import.meta.url), 'utf8').trim()
+
+// Channel behavior is shared without exposing owner workspace guidance to contacts.
+export const chatGuidance = (): string =>
+  readFileSync(new URL('../templates/chat-guidance.md', import.meta.url), 'utf8').trim()

package/src/ai-cli.ts

@@ -1,11 +1,12 @@
 import { parseArgs } from 'node:util'
 import { randomBytes } from 'node:crypto'
+import { join } from 'node:path'
 import { readModels, validateSelection, type AiPreset } from './ai.js'
 import { ControlStore } from './control-state.js'
 
 const {values,positionals}=parseArgs({allowPositionals:true,options:{cli:{type:'string'},model:{type:'string'},effort:{type:'string'}}})
 if (!process.env.EZ_CONTROL_DIR) throw new Error('Use this agent’s bound control directory')
-const catalog=await readModels()
+const catalog=await readModels(undefined,undefined,join(process.env.EZ_CONTROL_DIR,'cli','codex'))
 if(positionals[0]==='list')console.log(JSON.stringify(catalog))
 else if(positionals[0]==='select'){
   const preset:AiPreset={id:randomBytes(8).toString('hex'),name:[values.model||values.cli,values.effort].filter(Boolean).join(' · '),cli:values.cli||'',model:values.model,effort:values.effort}