@jc_stack/ez-agents 0.1.0-beta.21 → 0.1.0-beta.23

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.1.0-beta.23
+
+- Identify failed publisher API reads and missing release tags without exposing
+  credentials or signed asset URLs. Document verified tag/artifact staging and
+  recovery before a fresh publication attempt.
+- Include beta.22 incomplete-update-receipt recovery; the earlier unpublished
+  candidate remains preserved. Existing beta acceptance limits remain.
+
+## 0.1.0-beta.22
+
+- Ignore incomplete or malformed update-receipt directories until a valid,
+  atomically committed `job.json` exists. They have no activation authority and
+  must not take the host executor offline.
+
 ## 0.1.0-beta.21
 
 - Initialize fresh Telegram bots before reading their identity. Beta.19 could

package/docs/trusted-publishing.md

@@ -65,8 +65,28 @@ jobs from its latest attempt. Tag, PR and other workflow runs cannot shadow it;
 failed, pending or incomplete main CI cannot fall back to an older success.
 
 Create the `vVERSION` tag at that exact source commit and a **draft prerelease**
-with these assets, using native `gh release create --draft --prerelease` and
-`gh release upload` under existing release authority:
+with these assets under existing release authority. **Creating a draft release
+with `--target` does not create a Git tag.** Create and push the tag explicitly,
+then use `--verify-tag` to prevent staging against a missing remote tag:
+
+```sh
+# VERSION and SOURCE_SHA identify the reviewed, current-main candidate.
+git tag "v$VERSION" "$SOURCE_SHA"
+git push origin "refs/tags/v$VERSION"
+git ls-remote origin "refs/tags/v$VERSION"
+# Copy the already tested bytes, without rebuilding, to this exact basename.
+cp /absolute/tested-package.tgz /absolute/release/candidate.tgz
+gh release create "v$VERSION" --repo OWNER/REPO --verify-tag --draft --prerelease \
+  --title "v$VERSION" --notes-file /absolute/release/notes.md \
+  /absolute/release/candidate.tgz /absolute/release/release-receipt.json
+```
+
+If the tag already exists, read and verify its commit (peel annotated tags) rather
+than recreating or force-pushing it. Read back the draft by numeric ID and check
+asset names and downloaded SHA-256 before dispatch. `npm pack`'s default filename
+is not the publisher's asset name; GitHub asset labels do not rename the asset.
+Use `gh release upload` only to add a missing asset, never `--clobber` to replace
+candidate bytes or receipts. The required assets are:
 
 - `candidate.tgz`: the exact Mac-tested bytes from `npm pack --ignore-scripts`.
   Do not rebuild it on Actions.
@@ -114,6 +134,22 @@ identity on the release PR. A failed command after the publish call may mean npm
 accepted it: inspect registry state first. A rerun may verify an existing exact
 version; if the version is absent it refuses a second write. Reconcile first,
 then create a fresh authorized dispatch if appropriate. Never repeat or overwrite that version or silently repair tags.
+When validation fails, use the logged GitHub API path to identify the missing
+input. A tag lookup 404 is not evidence of a draft-release permission problem.
+A draft/asset 404 can mean absent evidence or insufficient access; verify with
+the existing authorized identity before diagnosing credentials. Do not broaden
+token permissions based on a generic 404.
+
+For a failure before the publish job starts, confirm that job was skipped and
+read npm for the exact version. If absent, repair missing staging inputs against
+the same approved commit/bytes, verify tag, asset names and digest, and create a
+fresh dispatch. If main or the package changes, prepare a new reviewed version;
+preserve the old draft instead of moving its tag or replacing its artifact.
+If any npm write may have started, use exact registry/artifact reconciliation
+above first. Publication recovery never means rolling back a running agent.
+Runtime upgrades and `failed`/`rolled-back` versus `recovery-required` recovery
+follow [upgrades](upgrades.md) under the installation's saved policy.
+
 Missing trust or registry access is an external dependency, not a reason to use
 a token workaround.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jc_stack/ez-agents",
-  "version": "0.1.0-beta.21",
+  "version": "0.1.0-beta.23",
   "private": false,
   "type": "module",
   "description": "A lightweight foundation for persistent business AI assistants using existing AI harnesses, workspaces and plugins.",

package/scripts/trusted-beta.mjs

@@ -87,8 +87,8 @@ export function tarManifest(path) {
   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`);
+async function responseBytes(response, max = MAX_ARTIFACT, context = 'release evidence') {
+  assert(response.ok, `HTTP ${response.status} while reading ${context}`);
   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); }
@@ -98,6 +98,8 @@ async function responseBytes(response, max = MAX_ARTIFACT) {
 export function githubClient(token, fetcher = fetch) {
   return async (path, binary = false) => {
     assert(path.startsWith('/repos/'), 'Invalid GitHub API path');
+    // Identify the failed read without logging tokens, response bodies or signed URLs.
+    const context = `GitHub GET ${path.split('?')[0]}`;
     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),
@@ -105,9 +107,12 @@ export function githubClient(token, fetcher = fetch) {
     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' }));
+      return responseBytes(await fetcher(location, { signal: AbortSignal.timeout(60_000), redirect: 'error' }), MAX_ARTIFACT, `${context} asset download`);
     }
-    const bytes = await responseBytes(response, binary ? MAX_ARTIFACT : 8 * 1024 * 1024);
+    if (response.status === 404 && path.includes('/git/ref/tags/')) {
+      throw new Error(`HTTP 404 while reading ${context}: release tag is missing or inaccessible; a draft release does not create its Git tag. Verify the remote tag at the reviewed source before dispatch.`);
+    }
+    const bytes = await responseBytes(response, binary ? MAX_ARTIFACT : 8 * 1024 * 1024, context);
     return binary ? bytes : JSON.parse(bytes.toString());
   };
 }

package/src/updates/control.mjs

@@ -7,6 +7,7 @@ import { digest, extract, newer, compatible, version, releaseContract, registryV
 export const read = async file => JSON.parse(await fs.readFile(file,'utf8'));
 export const missing = error => {if(error.code!=='ENOENT')throw error;return null;};
 export const targetId = value => {if(value!=='main'&&!/^[a-z][a-z0-9-]{0,39}$/.test(value))throw Error('Invalid update target');return value;};
+const jobId=/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
 export const updateHome = home => path.join(home,'updates');
 export async function state(home) {
   const config=await read(path.join(home,'config.json'));
@@ -77,12 +78,15 @@ export async function prepare(home,target,{file,release}) {
   } catch(error){await fs.rm(dir,{recursive:true,force:true});throw error;}
 }
 export function jobPath(home,id) {
-  if(!/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(id))throw Error('Invalid upgrade job ID');
+  if(!jobId.test(id))throw Error('Invalid upgrade job ID');
   return path.join(updateHome(home),id);
 }
 export async function jobs(home) {
   const entries=await fs.readdir(updateHome(home),{withFileTypes:true}).catch(error=>{if(error.code==='ENOENT')return [];throw error;});
-  return Promise.all(entries.filter(e=>e.isDirectory()&&/^[a-f0-9-]{36}$/.test(e.name)).map(e=>read(path.join(jobPath(home,e.name),'job.json'))));
+  // A job becomes visible only when its receipt is atomically committed. A crash
+  // before that point leaves no activation authority and must not stop the host.
+  const found=await Promise.all(entries.filter(e=>e.isDirectory()&&jobId.test(e.name)).map(e=>read(path.join(jobPath(home,e.name),'job.json')).catch(missing)));
+  return found.filter(Boolean);
 }
 async function requireSupervisor(directory) {
   const h=await read(path.join(directory,'supervisor.json'));

package/test/trusted-beta.test.mjs

@@ -222,3 +222,63 @@ test('workflow runs and attempt jobs are paginated before selecting required evi
     [jobsPath.replace('&page=1', '&page=2')]: { jobs: [job] },
   }));
 });
+
+test('GitHub errors identify the failed read without exposing credentials or signed URLs', async () => {
+  const missing = githubClient('private-token', async () => new Response('private-body', { status: 404 }));
+  await assert.rejects(missing('/repos/jdorado/ez-agents/git/ref/tags/v1.2.3-beta.1'), /GitHub GET .*\/git\/ref\/tags\/v1\.2\.3-beta\.1: release tag is missing or inaccessible/);
+  await assert.rejects(missing('/repos/jdorado/ez-agents/releases/123'), error => {
+    assert.match(error.message, /HTTP 404.*GitHub GET .*\/releases\/123/);
+    assert.doesNotMatch(error.message, /private-token|private-body|release tag/);
+    return true;
+  });
+  let request = 0;
+  const download = githubClient('private-token', async () => request++ === 0
+    ? new Response('', { status: 302, headers: { location: 'https://release-assets.githubusercontent.com/file?signature=private-signature' } })
+    : new Response('private-body', { status: 403 }));
+  await assert.rejects(download('/repos/jdorado/ez-agents/releases/assets/456', true), error => {
+    assert.match(error.message, /HTTP 403.*\/releases\/assets\/456 asset download/);
+    assert.doesNotMatch(error.message, /private-token|private-body|private-signature|signature=/);
+    return true;
+  });
+});
+
+test('staging recovery requires a real source tag and canonical asset before validating exact bytes', async t => {
+  const { validate } = await import('../scripts/trusted-beta.mjs');
+  const { readFile } = await import('node:fs/promises');
+  const dir = await mkdtemp(join(tmpdir(), 'beta-staging-recovery-'));
+  t.after(() => rm(dir, { recursive: true, force: true }));
+  await mkdir(join(dir, 'package'));
+  await writeFile(join(dir, 'package/package.json'), JSON.stringify(manifest));
+  execFileSync('tar', ['-czf', join(dir, 'candidate.tgz'), '-C', dir, 'package/package.json']);
+  const bytes = await readFile(join(dir, 'candidate.tgz'));
+  const candidateEnv = { ...env, RELEASE_SHA256: sha256(bytes) };
+  let tagExists = false, assetName = 'jc_stack-ez-agents-1.2.3-beta.1.tgz';
+  const reads = [];
+  const source = sourceApi();
+  const api = async path => {
+    reads.push(path);
+    if (path.includes('/git/ref/tags/') && !tagExists) {
+      return githubClient('test', async () => new Response('', { status: 404 }))(path);
+    }
+    if (path.endsWith('/releases/123')) return { id: 123, draft: true, prerelease: true, tag_name: `v${expected.version}`, assets: [
+      { id: 456, name: assetName, state: 'uploaded' }, { id: 457, name: 'release-receipt.json', state: 'uploaded' },
+    ] };
+    if (path.endsWith('/releases/assets/456')) return bytes;
+    if (path.endsWith('/releases/assets/457')) return Buffer.from(JSON.stringify({ ...receipt, sha256: candidateEnv.RELEASE_SHA256 }));
+    if (path.endsWith('/pulls/41')) return { merged: true, base: { repo: { full_name: expected.repository }, ref: 'main' }, merge_commit_sha: expected.sourceSha };
+    return source(path);
+  };
+  const output = join(dir, 'validated');
+  await assert.rejects(validate(output, candidateEnv, api), /release tag is missing/);
+  assert.ok(!reads.some(path => path.includes('/releases/')));
+  tagExists = true;
+  await assert.rejects(validate(output, candidateEnv, api), /Missing or ambiguous asset: candidate.tgz/);
+  assert.ok(!reads.some(path => path.includes('/releases/assets/')));
+  assetName = 'candidate.tgz';
+  await assert.rejects(validate(output, { ...candidateEnv, RELEASE_SHA256: '0'.repeat(64) }, api), /SHA256 mismatch/);
+  const result = await validate(output, candidateEnv, api);
+  assert.equal(result.sha256, sha256(bytes));
+  assert.deepEqual(await readFile(join(output, 'candidate.tgz')), bytes);
+  // Retry cannot silently replace an existing validated bundle.
+  await assert.rejects(validate(output, candidateEnv, api), /EEXIST/);
+});

package/test/updates.test.mjs

@@ -7,7 +7,7 @@ import { gzipSync } from 'node:zlib';
 import { spawn, execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { extract, digest, version, newer, compatible } from '../src/updates/artifact.mjs';
-import { prepare, submit, command, read, jobPath, eligibility } from '../src/updates/control.mjs';
+import { prepare, submit, command, read, jobPath, eligibility, jobs } from '../src/updates/control.mjs';
 import { perform, environment, packageManager } from '../src/updates/runtime.mjs';
 import { atomic, snapshot, compose } from '../src/plugins/manager.mjs';
 import { bindUpdates } from '../src/updates/binding.mjs';
@@ -252,6 +252,11 @@ test('missing or broken managers fail with repair guidance before installing or
 
 for(const provider of ['pnpm','corepack']) test(`supervisor with only ${provider} drains work, replaces host PID and recovers after restart`,async t=>{
  const f=await fixture(t),fake=path.join(f.root,'fake');await fs.mkdir(fake);
+ // A process may die after creating a job directory but before atomically
+ // committing its receipt. That directory must not block transport startup.
+ await fs.mkdir(path.join(f.home,'updates','d18e847a-bb59-49c6-96f3-27fdc43ca44f'));
+ await fs.mkdir(path.join(f.home,'updates','a'.repeat(36)));
+ assert.deepEqual(await jobs(f.home),[]);
  const hostCode=`import fs from 'node:fs';import path from 'node:path';const c=JSON.parse(fs.readFileSync(process.argv[2])).agents[0];const d=path.join(c.controlDir,'host-executor');fs.mkdirSync(d,{recursive:true});const beat=()=>{fs.writeFileSync(path.join(d,'heartbeat.json'),JSON.stringify({pid:process.pid,at:Date.now()}));};beat();const timer=setInterval(()=>{try{process.kill(Number(process.env.EZ_HOST_SUPERVISOR_PID),0)}catch{process.exit(0)}beat()},100);process.on('SIGTERM',()=>{clearInterval(timer);process.exit(0)});`;
  for(const dir of [f.old,f.source]) {
   await fs.mkdir(path.join(dir,'node_modules/tsx/dist'),{recursive:true});await fs.writeFile(path.join(dir,'node_modules/tsx/dist/loader.mjs'),'');