@uchibeke/gallivant 0.0.0-stage → 0.2.1

package/lib/provider_health.mjs

@@ -0,0 +1,55 @@
+import { join } from "node:path";
+import { readJson, writeJsonAtomic } from "./fs.mjs";
+import { boundedCall, EXECUTION_LIMITS, nextAttempt } from "./execution_io.mjs";
+export function makeProviderHealth({ home, file = join(home, "provider-health.json"), clock = Date, limits = {}, probe, jitter = Math.random }) {
+  const bounds = { ...EXECUTION_LIMITS, ...limits }, pending = new Map();
+  const key = (provider, account) => JSON.stringify([provider, account]);
+  const read = () => {
+    const s = readJson(file, { version: 1, scopes: {} });
+    if (s.version !== 1) throw new Error("unsupported provider health version; restore a compatible backup before dispatch");
+    return s;
+  };
+  const get = (provider, account = "operator") => {
+    const s = read();
+    const id = key(provider, account), saved = s.scopes[id];
+    if (!saved) return { ok: false, detail: "provider/account check pending" };
+    // Fence due scopes before refresh starts, including those waiting for a
+    // probe worker. A read never probes; restart uses the same saved deadline.
+    if (saved.ok && (pending.has(id) || clock.now() >= (saved.nextAttemptAt ?? saved.observedAt + bounds.progressMs))) return { ...saved, ok: false, detail: "provider/account health refresh pending; awaiting the coordinator's next probe" };
+    if (saved.ok && clock.now() > saved.observedAt + bounds.progressMs * 2) return { ...saved, ok: false, detail: "provider/account health is stale; awaiting the coordinator's next probe" };
+    return saved;
+  };
+  const refresh = async scopes => {
+    const queue = [], errors = [];
+    // Complete schema/deadline reads before registering any waiters. A refused
+    // state read must not strand scopes that have not obtained a worker yet.
+    const due = scopes.filter(([provider, account]) => !pending.has(key(provider, account)) && clock.now() >= (get(provider, account).nextAttemptAt || 0));
+    for (const [provider, account] of due) {
+      const id = key(provider, account);
+      if (pending.has(id)) continue;
+      let finish;
+      pending.set(id, new Promise(resolve => { finish = resolve; }));
+      queue.push({ provider, account, id, finish });
+    }
+    const worker = async () => {
+      for (let scope = queue.shift(); scope; scope = queue.shift()) {
+        const { provider, account, id, finish } = scope;
+        try {
+          let result;
+          try { result = await boundedCall(signal => probe(provider, account, signal), bounds); }
+          catch (e) { result = { ok: false, detail: e.code || "provider check failed", retryAfterMs: e.retryAfterMs }; }
+          const s = read();
+          const failures = result.ok ? 0 : (s.scopes[id]?.failures || 0) + 1;
+          s.scopes[id] = { ...result, failures, observedAt: clock.now(), nextAttemptAt: result.ok ? clock.now() + bounds.progressMs : nextAttempt(clock.now(), failures, result.retryAfterMs, bounds, jitter) };
+          writeJsonAtomic(file, s);
+        } catch (error) { errors.push(error); }
+        finally { pending.delete(id); finish(); }
+      }
+    };
+    await Promise.all(Array.from({ length: Math.min(bounds.concurrency, queue.length) }, worker));
+    if (errors.length) throw errors[0];
+  };
+  // Waiting only joins a probe already scheduled by the coordinator. It cannot
+  // create provider I/O, and resolves after persistence, including failed writes.
+  return { get, refresh, whenRefreshed: (provider, account = "operator") => pending.get(key(provider, account)) || null };
+}

package/lib/public-format.mjs

@@ -0,0 +1,31 @@
+// GitHub-facing names live here. Read old spellings indefinitely; write only the neutral format.
+export const BRANCH_PREFIX = "work/";
+export const BRANCH_PREFIXES = [BRANCH_PREFIX, "gallivant/"];
+export const BLOCK_OPEN = "<!-- work-session";
+export const BLOCK_OPENS = [BLOCK_OPEN, "<!-- gallivant"];
+export const RECEIPT_TAG = "work-attestations";
+export const RECEIPT_TAGS = [RECEIPT_TAG, "gallivant-attestations"];
+export const ROUND_MARKER = "<!-- work-round -->";
+export const NUDGE_MARKER = "<!-- work-nudge -->";
+export const RESET_MARKER = "<!-- work-reset -->";
+export const MARKER_ALIASES = new Map([
+  [ROUND_MARKER, [ROUND_MARKER, "<!-- gallivant round -->"]],
+  [NUDGE_MARKER, [NUDGE_MARKER, "<!-- gallivant nudge -->"]],
+  [RESET_MARKER, [RESET_MARKER, "<!-- gallivant reset -->"]],
+]);
+export const READY_LABEL = "status:ready-for-review";
+export const NEEDS_LABEL = "status:needs-attention";
+export const LABEL_ALIASES = new Map([
+  [READY_LABEL, [READY_LABEL, "gallivant:ready-for-human"]],
+  [NEEDS_LABEL, [NEEDS_LABEL, "gallivant:needs-human"]],
+]);
+
+export const markerAliases = marker => [...MARKER_ALIASES.values()].find(names => names.includes(marker)) ?? [marker];
+export const hasMarker = (body, marker) => markerAliases(marker).some(value => String(body || "").includes(value));
+export const labelAliases = label => [...LABEL_ALIASES.values()].find(names => names.includes(label)) ?? [label];
+
+/** GitHub labels arrive as objects from GraphQL or strings from local callers. Only our two legacy aliases count. */
+export const hasLegacyStatusLabels = labels => (labels ?? []).some(label => {
+  const name = typeof label === "string" ? label : label?.name;
+  return typeof name === "string" && [...LABEL_ALIASES.values()].some(([, ...legacy]) => legacy.includes(name.toLowerCase()));
+});

package/lib/public_output.mjs

@@ -0,0 +1,49 @@
+// Public prose is about the change, not the runner. This is a formatting policy, not a network boundary: sessions
+// still have their own GitHub tools. The daemon validates what they actually published before signalling readiness.
+import { shortHash } from "./hash.mjs";
+
+const BRAND = /gallivant/i;
+const nulViolation = (value, field) => String(value ?? "").includes("\0") ? `${field} contains NUL bytes` : null;
+
+/** GitHub CLI arguments cannot contain NUL, including during recovery-only migration. */
+export function assertNoNul(value, field = "text") {
+  const violation = nulViolation(value, field);
+  if (violation) throw new Error(`Public text rejected: ${violation}.`);
+  return value;
+}
+
+export function publicTextViolation(value, field = "text") {
+  const text = String(value ?? "");
+  return nulViolation(text, field) || (BRAND.test(text) ? `${field} mentions the runner name` : null);
+}
+
+/** Validate daemon-authored text before an outbound write. Never rewrite prose, evidence, URLs or quoted findings. */
+export function assertPublicText(value, field = "text") {
+  assertNoNul(value, field);
+  const violation = publicTextViolation(value, field);
+  if (violation) throw new Error(`Public text rejected: ${violation}. Describe the change without runner branding.`);
+  return value;
+}
+
+export const publicPrViolations = pr => [
+  publicTextViolation(pr.title, "PR title"),
+  publicTextViolation(pr.body, "PR body"),
+].filter(Boolean);
+
+export function publicCommentViolations(comments) {
+  return comments.map(c => publicTextViolation(c.body, `${c.public_kind ?? (c.path ? "inline" : "PR")} comment ${c.id}`)).filter(Boolean);
+}
+
+/** Only comments selected by the caller's ownership and rollout-time checks belong in this fingerprint. */
+export const publicReviewHash = (pr, comments = []) => shortHash(JSON.stringify({
+  title: pr.title ?? "", body: pr.body ?? "",
+  comments: comments.map(c => [c.public_kind ?? (c.path ? "inline" : "issue"), String(c.id), c.body ?? ""]).sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b))),
+}));
+
+export function publicCorrection(violations) {
+  return [
+    "The published pull request does not meet the public text policy:",
+    ...violations.map(v => `- ${v}`),
+    "Edit the existing PR title/body or your identified comments to describe the actual change without mentioning Gallivant (case-insensitive). Preserve accurate evidence, criterion outcomes and limitations; use another concrete evidence pointer when a path contains the name. Do not invent passing evidence, rewrite commits, open another PR, or remove the completion receipt. Machine metadata is managed separately. A wording-only correction needs no new commit.",
+  ].join("\n");
+}

package/lib/release_package.mjs

@@ -0,0 +1,154 @@
+// Release records qualify the existing package; they never dispatch task work.
+import { createHash } from 'node:crypto';
+import { readFileSync, writeFileSync, lstatSync, rmSync } from 'node:fs';
+import { join, resolve, isAbsolute } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { buildPluginPackage, validatePublicRelease, runtimeFile, payloadChange, packagingControl, packagingControlInventory } from './plugin_package.mjs';
+import { redact } from './execution_io.mjs';
+import { canonical } from './learning_data.mjs';
+
+const root = fileURLToPath(new URL('../', import.meta.url));
+const digest = bytes => createHash('sha256').update(bytes).digest('hex');
+const json = value => JSON.stringify(value, null, 2) + '\n';
+const hash = value => digest(canonical(JSON.parse(JSON.stringify(value))));
+const fail = message => { throw new Error(message); };
+const sha = value => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+const text = value => typeof value === 'string' && value.trim().length > 0 && value.length <= 1000 && redact(value) === value && !/[\x00-\x1f]/.test(value);
+const exact = (value, fields) => value && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).every(key => fields.includes(key));
+const HANDOFF_FILES = ['listing.md', 'release-notes.md', 'review-cases.json', 'START-HERE.md', 'RUNTIME.md'];
+const runtimeConfiguration = manifest => Object.fromEntries(['resource', 'requirements', 'exports', 'coreVersion', 'operationVersion', 'taskVersion', 'executionVersion'].map(key => [key, manifest[key]]));
+
+// Each observation is a concrete evidence pointer, not a boolean attestation.
+// The operator must retain the corresponding observed records for review.
+export const RELEASE_CHECKS = Object.freeze({
+  integration: { scopes: ['core'], cases: ['mergedFoundation', 'reconciledJob', 'mergedExports', 'pinnedArtifact', 'remainingCriteria', 'humanMerge'], next: 'Reconcile PR #414 and the existing job; pin merged M5 bytes, then reuse or create exactly one workflow integration successor against staging. Require human merge.' },
+  deployment: { scopes: ['core', 'tools', 'deployment'], cases: ['humanApproval', 'revision', 'httpsMcp', 'oauthDiscovery', 'durableState', 'singleCoordinator', 'workerCredentials', 'health', 'readiness', 'quotas', 'artifactAuthorization', 'restartNoDuplicate'], next: 'Deploy the pinned runtime through the APort recipe to the authorized target; record revision, scoped discovery, durable restart and coordinator checks.' },
+  agents: { scopes: ['core', 'tools', 'deployment'], cases: ['implementation', 'forcedCorrection', 'verifiedFiles', 'tests', 'onePr', 'restart', 'sessionContinuity', 'usage'], next: 'Reconcile the shared USD 10 ledger, configure OPENAI_AGENTS_LIVE_HOME/PRD/REPO/CAMPAIGN_LEDGER, then run existing G8 implementation and correction phases sequentially.' },
+  cloud: { scopes: ['core', 'tools', 'deployment'], cases: ['implementation', 'forcedCorrection', 'verifiedFiles', 'tests', 'onePr', 'restart', 'nativeOrSuccessorContinuity', 'usage'], next: 'Implement and qualify the supported environment-to-repository check at the Cloud adapter; configure CODEX_CLOUD_LIVE_HOME/PRD/REPO/CAMPAIGN_LEDGER before existing G8 phases.' },
+  host: { scopes: ['core', 'tools', 'plugin', 'deployment'], cases: ['installedCandidate', 'freshAccount', 'questions', 'requirements', 'readiness', 'availableRemoteHarness', 'implementation', 'progress', 'files', 'onePr', 'correction', 'sidebar', 'panel', 'reopenSameTask'], next: 'After qualified deployment, install this exact ZIP in actual ChatGPT; exercise and capture the fresh-account task and supported sidebar/panel reconnect.' },
+  recovery: { scopes: ['core', 'tools', 'plugin', 'deployment'], cases: ['accountIsolation', 'expiredAuthentication', 'staleRevision', 'duplicateStart', 'providerOutage', 'unsupportedCancellation'], next: 'Exercise each negative scenario against the actual service/UI using isolated accounts; retain observed recovery and non-overlap records.' },
+  reviewer: { scopes: ['core', 'tools', 'plugin', 'deployment'], cases: ['cleanSession', 'dedicatedTenant', 'sampleRepository', 'usableAccount', 'allowance', 'noVpnMfaSmsMagicLink', 'securePortalStorage'], next: 'Provision and test dedicated reviewer access in a clean session; keep credentials and private instructions only in secure operator storage/portal.' },
+  publisher: { scopes: ['plugin', 'deployment'], cases: ['businessIdentity', 'organizationPermissions', 'eligibleProjectResidency', 'domainChallengePreservesOthers', 'customerResidencyUnchanged', 'legalProductSupportUrls'], next: 'Record APort business/org/project eligibility, working URLs and the assigned domain challenge without overwriting existing tokens.' },
+  scans: { scopes: ['core', 'tools', 'plugin', 'deployment'], cases: ['package', 'mcp', 'skills'], next: 'Upload the candidate to the authorized portal draft and record package/skill scans; use MCPs > connected server > Rescan for the exact deployment. Do not submit.' },
+  media: { scopes: ['plugin', 'deployment'], cases: ['authenticScreenshots', 'accessibleDemoRecording'], next: 'Capture the actual installed host and publish the authorized demo recording at the configured URL; verify reviewer access.' },
+  upgrade: { scopes: ['core', 'tools', 'deployment'], cases: ['backup', 'compatibleUpgrade', 'rollback', 'queuedIdentities', 'activeIdentities', 'savedState', 'unsupportedMigrationRefused'], next: 'Rehearse the existing state check/backup/migrate/restore commands with matching runtime manifests, preserved identities and a safe incompatible-version refusal.' },
+});
+
+export function readReleaseJson(path) {
+  const stat = lstatSync(path);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1048576) fail('Release JSON must be a regular non-symlink file of at most 1 MiB');
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+function fileBytes(dir, path) {
+  if (typeof path !== 'string' || !path || isAbsolute(path) || path.split(/[\\/]/).some(p => !p || p === '.' || p === '..')) fail('Unsafe release payload path');
+  let current = resolve(dir);
+  for (const part of path.split('/')) {
+    current = join(current, part);
+    if (lstatSync(current).isSymbolicLink()) fail('Release payload cannot contain symlinks');
+  }
+  const stat = lstatSync(current);
+  if (!stat.isFile() || stat.size > 64 * 1024 * 1024) fail('Release payload must be a bounded regular file');
+  return readFileSync(current);
+}
+export function releaseIdentity(manifest, deployment) {
+  if (!sha(manifest.coreSha256) || !sha(manifest.hashes?.plugin) || !sha(manifest.hashes?.operations) || !sha(manifest.hashes?.runtime) || !sha(manifest.dependencyLockSha256)) fail('Incomplete package manifest hashes');
+  if (!exact(deployment, ['revision', 'configurationSha256', 'endpoint']) || !text(deployment.revision) || !sha(deployment.configurationSha256) || deployment.endpoint !== manifest.endpoint) fail('Record the actual deployment revision, non-secret configuration digest and matching endpoint');
+  return {
+    core: hash({ artifact: manifest.coreSha256, lock: manifest.dependencyLockSha256, payload: manifest.payloadHashes, packagingControls: manifest.packagingControlHashes }),
+    tools: hash({ operations: manifest.hashes.operations, schema: manifest.schemaHashes, submissionSchema: manifest.submissionSchemaSha256 }),
+    plugin: manifest.hashes.plugin,
+    // Bind functional runtime settings, excluding audit-only source provenance.
+    deployment: hash({ ...deployment, runtime: runtimeConfiguration(manifest) }),
+  };
+}
+export function evaluateRelease({ manifest, deployment, evidence = { version: 1, checks: {} } }) {
+  if (!exact(evidence, ['version', 'checks', 'states']) || evidence.version !== 1 || !exact(evidence.checks, Object.keys(RELEASE_CHECKS))) fail('Unsupported release evidence schema; preserve the prior record and migrate explicitly');
+  const identity = releaseIdentity(manifest, deployment);
+  const checks = {}, blockers = [];
+  const publicCandidate = manifest.classification === 'public-candidate-unqualified' && manifest.sourceVerified === true && Array.isArray(manifest.uncommittedPayload) && manifest.uncommittedPayload.length === 0;
+  if (!publicCandidate) blockers.push({ id: 'candidate', next: 'Build the public candidate from clean merged source with authentic assets; fixtures cannot qualify.' });
+  for (const [id, rule] of Object.entries(RELEASE_CHECKS)) {
+    const record = evidence.checks[id];
+    if (record && (!exact(record, ['kind', 'status', 'at', 'bindings', 'observations']) || !exact(record.bindings, rule.scopes) || !exact(record.observations, rule.cases))) fail(`Unsupported ${id} evidence fields; keep secrets and private instructions outside release records`);
+    if (record && (!['live', 'offline', 'fixture'].includes(record.kind) || !['passed', 'failed', 'blocked', 'unverified'].includes(record.status) || typeof record.at !== 'string' || !Number.isFinite(Date.parse(record.at)) || Object.values(record.bindings).some(value => !sha(value)) || Object.values(record.observations).some(value => !text(value)))) fail(`Invalid ${id} observation; use bounded non-secret pointers and SHA-256 bindings`);
+    const bound = record && rule.scopes.every(scope => record.bindings?.[scope] === identity[scope]);
+    const currentLive = record?.kind === 'live' && Date.parse(record.at) <= Date.now();
+    const complete = currentLive && record.status === 'passed' && rule.cases.every(name => text(record.observations?.[name]));
+    const status = !record ? 'missing' : !bound ? 'stale' : currentLive && ['failed', 'blocked'].includes(record.status) ? record.status : complete && publicCandidate ? 'passed' : 'unverified';
+    checks[id] = { status, required: rule.cases, scopes: rule.scopes };
+    if (status !== 'passed') blockers.push({ id, status, next: rule.next });
+  }
+  // Later owner actions are independently recorded, never inferred from readiness.
+  const stateNames = ['codeMerged', 'submitted', 'approved', 'published'];
+  if (evidence.states && !exact(evidence.states, stateNames)) fail('Unsupported publication state');
+  const states = {};
+  for (const name of stateNames) {
+    const record = evidence.states?.[name];
+    if (record && (!exact(record, ['at', 'pointer', 'identity']) || !text(record.pointer) || !Number.isFinite(Date.parse(record.at)) || Date.parse(record.at) > Date.now() || !exact(record.identity, Object.keys(identity)) || Object.values(record.identity).some(value => !sha(value)))) fail('Invalid owner state evidence');
+    states[name] = !!record && Object.keys(identity).every(key => record.identity[key] === identity[key]);
+  }
+  const liveQualified = ['integration', 'deployment', 'agents', 'cloud', 'host', 'recovery', 'upgrade'].every(id => checks[id].status === 'passed');
+  const submissionReady = !blockers.length && states.codeMerged;
+  if (!states.codeMerged) blockers.push({ id: 'codeMerged', next: 'Record the human merge of this exact candidate source; a review PR is not merge evidence.' });
+  return { version: 1, status: submissionReady ? 'submission-ready' : 'needs-human', identity, checks, blockers, rerun: blockers.filter(b => RELEASE_CHECKS[b.id]).map(b => b.id), states: { ...states, liveQualified, submissionReady } };
+}
+
+export function verifyReleasePayload(dir, manifest, { sourceRoot = root } = {}) {
+  const files = { [manifest.coreArtifact]: manifest.coreSha256, 'aport-task-delivery.zip': manifest.hashes?.plugin, 'runtime.json': manifest.hashes?.runtime, 'operations.json': manifest.hashes?.operations };
+  if (!exact(manifest.handoffHashes, HANDOFF_FILES)) fail('Incomplete handoff hashes; rebuild the release candidate');
+  for (const path of HANDOFF_FILES) files[path] = manifest.handoffHashes[path];
+  if (!manifest.assetHashes || typeof manifest.assetHashes !== 'object' || Array.isArray(manifest.assetHashes) || !Object.keys(manifest.assetHashes).length) fail('Incomplete plugin asset hashes; rebuild the release candidate');
+  for (const [path, expected] of Object.entries(manifest.assetHashes)) files[`plugin/${path}`] = expected;
+  for (const [path, expected] of Object.entries(files)) if (!sha(expected) || digest(fileBytes(dir, path)) !== expected) fail(`Candidate bytes changed: ${path}; rebuild and repeat affected checks`);
+  if (hash(runtimeConfiguration(readReleaseJson(join(dir, 'runtime.json')))) !== hash(runtimeConfiguration(manifest))) fail('Runtime configuration differs from the package manifest; rebuild before qualification');
+  // Compare the source payload, including new/deleted packaging inputs, at validation time.
+  for (const [path, expected] of Object.entries(manifest.payloadHashes || {})) {
+    if (digest(fileBytes(sourceRoot, path)) !== expected) fail(`Source payload changed: ${path}; rebuild before qualification`);
+  }
+  const tracked = execFileSync('git', ['ls-tree', '-r', '-z', '--name-only', 'HEAD'], { cwd: sourceRoot, encoding: 'utf8', maxBuffer: 16777216 }).split('\0').filter(path => runtimeFile(path) && !path.startsWith('node_modules/')).sort();
+  const packed = Object.keys(manifest.payloadHashes || {}).filter(path => !path.startsWith('node_modules/')).sort();
+  if (JSON.stringify(tracked) !== JSON.stringify(packed)) fail('Source payload paths changed; rebuild before qualification');
+  const controls = manifest.packagingControlHashes;
+  if (!controls || typeof controls !== 'object' || Array.isArray(controls) || Object.entries(controls).some(([path, value]) => !packagingControl(path) || !sha(value))) fail('Missing or invalid packaging-control inventory; rebuild before qualification');
+  if (hash(packagingControlInventory(sourceRoot, 'HEAD')) !== hash(controls)) fail('Committed packaging controls changed; rebuild before qualification');
+  for (const [path, expected] of Object.entries(controls)) if (digest(fileBytes(sourceRoot, path)) !== expected) fail(`Packaging control changed: ${path}; rebuild before qualification`);
+  const changes = execFileSync('git', ['status', '--porcelain=v1', '-z', '--untracked-files=all', '--no-renames', '--ignored=matching'], { cwd: sourceRoot, encoding: 'utf8', maxBuffer: 1048576 }).split('\0').filter(Boolean).map(line => line.slice(3));
+  if (changes.some(payloadChange)) fail('Uncommitted source/packaging inputs; rebuild the candidate after committing them');
+  return true;
+}
+
+export function releasePreflight(config, setup = {}) {
+  const packageCheck = validatePublicRelease(config);
+  const requirements = {
+    target: 'Confirm the authorized APort deployment target and permanent domain.',
+    providerAccess: 'Verify the selected model/environment/repository through provider setup, not CLI sign-in alone.',
+    repositoryAccess: 'Verify disposable repository and branch authority for the campaign.',
+    reviewerAccess: 'Test a dedicated reviewer account/tenant in a clean session; store private setup in the portal.',
+    executionAllowance: 'Reconcile the existing shared USD 10 campaign ledger, including unknown prior spend, before reserving another phase.',
+  };
+  if (!exact(setup, Object.keys(requirements))) fail('Setup accepts only concrete prerequisite evidence pointers');
+  const blockers = packageCheck.errors.map(next => ({ id: 'publisher-package', next }));
+  for (const [id, next] of Object.entries(requirements)) if (!text(setup[id])) blockers.push({ id, next });
+  return { version: 1, status: blockers.length ? 'needs-human' : 'prepared-unqualified', submissionReady: false, blockers };
+}
+
+export function assembleRelease({ config, out, coreVersion, sourceCommit, deployment, evidence, internal = false }) {
+  // The existing builder refuses occupied outputs and owns archive creation.
+  const manifest = buildPluginPackage({ config, out, coreVersion, sourceCommit, internal });
+  try {
+    const evaluation = evaluateRelease({ manifest, deployment, evidence });
+    manifest.release = { deployment, identity: evaluation.identity, observedAt: new Date().toISOString(), states: evaluation.states };
+    writeFileSync(join(out, 'evidence.json'), json(evidence || { version: 1, checks: {} }));
+    writeFileSync(join(out, 'qualification.json'), json({ deployment, ...evaluation }));
+    writeFileSync(join(out, 'listing.md'), `${config.listing?.longDescription || 'Scoped task delivery through APort.'}\n`);
+    writeFileSync(join(out, 'release-notes.md'), `${config.publication?.release_notes || 'Release candidate assembled. Run release:validate for current qualification results.'}\n`);
+    writeFileSync(join(out, 'review-cases.json'), json(config.review || {}));
+    writeFileSync(join(out, 'START-HERE.md'), `# Release candidate\n\nThis file contains stable setup instructions. Offline checks are not live qualification.\n\nInstall ${manifest.coreArtifact} with npm install --ignore-scripts. Import the combined aport-task-delivery.zip in the supported host after qualifying the deployment. RUNTIME.md contains the existing runtime, state migration, backup and rollback commands. manifest.json binds package, schema, lock and payload bytes. Its release states and the saved qualification.json results are assembly-time snapshots; qualification.json also supplies the recorded deployment.\n\nRun npm run release:validate -- --out "$RELEASE_DIR" from the exact source checkout. Read the returned JSON status, checks, blockers, rerun and states for current qualification. Validation reads the latest evidence.json and checks it against this candidate and the recorded deployment; it does not refresh the saved qualification.json. Follow only the current blockers and their next steps. Rerun validation after updating evidence and before handoff. Use docs/release-qualification.md for the opt-in provider and host procedures.\n\nPrivate reviewer instructions and credentials belong only in secure operator storage/portal. Metadata or skill changes require a new ZIP; live MCP updates require a server rescan. Submit, approve and publish are separate owner actions, never inferred here.\n`);
+    // The manifest is the trust anchor; only evidence/qualification records are mutable.
+    // Plugin staging files already have hashes from the shared package builder.
+    manifest.handoffHashes = Object.fromEntries(HANDOFF_FILES.map(path => [path, digest(fileBytes(out, path))]));
+    writeFileSync(join(out, 'manifest.json'), json(manifest));
+    return { manifest, evaluation };
+  } catch (error) { rmSync(out, { recursive: true, force: true }); throw error; }
+}

package/lib/repository_files.mjs

@@ -0,0 +1,86 @@
+// Files carried into a session must stay in the repository, including through symlinks.
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { lstatSync, mkdirSync, realpathSync, renameSync, rmSync, writeFileSync, readFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+
+/** Refuse links at every component. The root itself may use the OS's /tmp or /var alias. */
+export function repositoryPath(root, rel, { createParents = false, allowGit = false, allowMissingParents = false } = {}) {
+  if (typeof rel !== "string" || !rel || isAbsolute(rel) || /[\\\0]/.test(rel) || rel.split("/").includes("..")) {
+    throw new Error(`unsafe repository path: ${rel}`);
+  }
+  const parts = rel.split("/").filter(p => p && p !== ".");
+  if (!parts.length || (!allowGit && parts.some(p => p.toLowerCase() === ".git"))) throw new Error(`unsafe repository path: ${rel}`);
+  const base = realpathSync(root);
+  const target = resolve(base, ...parts);
+  const within = relative(base, target);
+  if (!within || within === ".." || within.startsWith(`..${sep}`) || isAbsolute(within)) throw new Error(`${rel} leaves the repository`);
+  let path = base;
+  for (const [i, part] of parts.entries()) {
+    path = join(path, part);
+    const parent = i < parts.length - 1;
+    let st;
+    try { st = lstatSync(path); }
+    catch (e) {
+      if (e.code !== "ENOENT") throw e;
+      if (parent && createParents) mkdirSync(path, { mode: 0o755 });
+      else if (parent && !allowMissingParents) throw e;
+      continue;
+    }
+    if (st.isSymbolicLink()) throw new Error(`${rel} contains a symlink; use a regular file inside the repository`);
+    if (parent ? !st.isDirectory() : !st.isFile()) throw new Error(`${rel} is not a regular repository file`);
+  }
+  return target;
+}
+
+export function readRepositoryText(root, rel) {
+  return readFileSync(repositoryPath(root, rel), "utf8");
+}
+
+/** Canonical Git-relative spelling using the same containment and link checks. */
+export function repositoryRelativePath(root, rel, options) {
+  return relative(realpathSync(root), repositoryPath(root, rel, options)).split(sep).join("/");
+}
+
+/** Reject portable file/directory aliases without reading repository contents. */
+export function assertRepositoryTargets(paths, trackedPaths) {
+  const folded = path => path.normalize("NFC").toUpperCase().toLowerCase().normalize("NFC");
+  const known = new Map(), targets = new Set();
+  const components = path => {
+    if (typeof path !== "string" || !path || isAbsolute(path) || path.includes("\0") || path.split("/").some(part => !part || part === "." || part === "..")) throw new Error("invalid tracked repository paths; retrieve complete Git path metadata");
+    return path.split("/");
+  };
+  const add = (path, check) => {
+    const parts = components(path);
+    let level = known;
+    for (const [i, part] of parts.entries()) {
+      const key = folded(part), kind = i === parts.length - 1 ? "file" : "directory";
+      let node = level.get(key);
+      if (check && node && (node.spellings.size !== 1 || !node.spellings.has(part) || node.kinds.size !== 1 || !node.kinds.has(kind))) throw new Error("result file aliases an existing repository path");
+      if (!node) { node = { spellings: new Set(), kinds: new Set(), children: new Map() }; level.set(key, node); }
+      node.spellings.add(part); node.kinds.add(kind); level = node.children;
+    }
+  };
+  if (!Array.isArray(paths) || !Array.isArray(trackedPaths)) throw new Error("tracked repository paths unavailable; retrieve complete Git path metadata");
+  for (const path of trackedPaths) add(path, false);
+  for (const path of paths) {
+    const target = folded(path);
+    if (targets.has(target)) throw new Error("duplicate canonical result file");
+    targets.add(target);
+    add(path, true);
+  }
+}
+
+/** Replace the directory entry, never truncate an existing link or hard link's target. */
+export function writeRepositoryText(root, rel, text, { mode = null, allowGit = false } = {}) {
+  const path = repositoryPath(root, rel, { createParents: true, allowGit });
+  if (mode === null) {
+    try { mode = lstatSync(path).mode & 0o777; }
+    catch (e) { if (e.code !== "ENOENT") throw e; mode = 0o644; }
+  }
+  const tmp = join(dirname(path), `.gallivant-${randomUUID()}.tmp`);
+  try {
+    writeFileSync(tmp, text, { flag: "wx", mode, flush: true });
+    repositoryPath(root, rel, { allowGit });
+    renameSync(tmp, path);
+  } finally { rmSync(tmp, { force: true }); }
+}