rewritable 0.8.1 → 0.9.0

package/src/identity.mjs

@@ -14,12 +14,12 @@
 // doc.test.mjs). Drift fails loudly. KEEP IN STEP with tools/self-description.mjs.
 
 import { tagHasFrozenAttr } from './apply-edits.mjs';
-import { parseSkillZone } from './skill-manifest.mjs';
+import { parseSkillZone, parseAgentZone } from './skill-manifest.mjs';
 
 export const SCHEMA_TAG = 'self-description/1';
 // Mirror of tools/self-description.mjs AFFORDANCE_KINDS / PROVENANCES — used by the
 // declared-projection conformance gate (declaredIsConforming). Keep in step.
-export const AFFORDANCE_KINDS = ['view', 'edit-surface', 'tool', 'compute', 'hook'];
+export const AFFORDANCE_KINDS = ['view', 'edit-surface', 'tool', 'compute', 'hook', 'agent'];
 export const PROVENANCES = ['first-party', 'installed'];
 
 // kind -> registered provider bundle (spec §4). Each provider is {kind,name,label};
@@ -86,6 +86,7 @@ export function buildSelfDescription({ doc, uuid, kind, frozenZones }) {
   const affordances = [
     ...(KIND_PROVIDERS[kind] || []).map((p) => ({ ...p, provenance: 'first-party' })),
     ...parseSkillZone(doc),
+    ...parseAgentZone(doc), // I12/SD-04 — installed agents (kind:'agent', name:role)
   ];
   return {
     rwa: SCHEMA_TAG,

package/src/install.mjs

@@ -0,0 +1,206 @@
+// `rwa install <skill.rwa-skill.json> <skill-host.html>` (v0.9 open-items spec §3 / I11).
+//
+// The offline, headless counterpart of the seed's interactive install dialog
+// (seeds/rewritable.html showSkillInstallDialog / runtimeInstallSkill). It gates a
+// skill envelope through the SAME trust checks as the seed — Ed25519 signature
+// verify, validateInstall (unsigned-capability / compute-with-perms / permission
+// grammar), and the dynamic-import() hard-reject — then splices the verified
+// envelope into the frozen `<div data-rwa-frozen id="rwa-skills">` zone inside
+// INLINE_DOC and re-bakes the file atomically.
+//
+// The CLI is the sole AUDITED exception to runtime-sole-writer (Invariant 19/39):
+// applyEdits would REJECT a frozen-zone write, so install does a direct zone splice
+// + replaceInlineDoc re-bake — writing the byte-identical zone form the seed's
+// runtimeRegionCommit produces (skillId-sorted, base64(JSON(envelope)) blocks), so
+// it re-verifies at the seed's boot. There is no dialog to consent in, so an
+// explicit `--yes` is required; gate failures are final and `--yes` cannot override
+// them.
+//
+// buildSkillZone here is a hand-mirror of the seed's buildSkillZone (there is no CLI
+// zone-builder elsewhere — parseSkillZone in skill-manifest.mjs only READS). Same
+// mirror discipline as cli/src/apply-edits.mjs mirrors the seed apply path.
+
+import { readFile } from 'node:fs/promises';
+import { skillId, verifyEnvelope, validateInstall, parseSkillZone, levenshtein, skeletonDistance, normalizeName } from './skill-manifest.mjs';
+import { extractInlineDoc, replaceInlineDoc } from './seed.mjs';
+import { tagHasFrozenAttr } from './apply-edits.mjs';
+import { CliError } from './edit.mjs';
+import { atomicWrite } from './atomic-write.mjs';
+
+const SKILL_BLOCK_RE = /<script\s+type="application\/rwa-skill\+json">([\s\S]*?)<\/script>/g;
+
+/** Mirror of the seed's _skCodeForbidden — refuse dynamic import() before any install.
+ *  The seed enforces this at install AND invoke; the CLI enforces it at install (it never
+ *  invokes). A code-loading channel the bridge/CSP can't see, so it is refused outright. */
+export function codeForbidden(code) {
+  return /\bimport\s*\(/.test(String(code || '')) ? 'dynamic_import_forbidden' : null;
+}
+
+/** Hand-mirror of the seed buildSkillZone: CANONICAL — sorted by skillId so the bytes are
+ *  install-order-independent; each envelope re-emitted as utf-8 base64 inside its <script>
+ *  block (matches parseSkillZone's read format) so it re-verifies at the seed's boot. */
+export function buildSkillZone(envelopes) {
+  const blocks = envelopes
+    .map((e) => ({ id: skillId(e.skill.name, e.skill.author_pubkey), e }))
+    .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+    .map((x) => '<script type="application/rwa-skill+json">' + Buffer.from(JSON.stringify(x.e)).toString('base64') + '</script>')
+    .join('');
+  return '<div data-rwa-frozen id="rwa-skills">' + blocks + '</div>';
+}
+
+/** Locate the frozen #rwa-skills zone — mirror of the seed's _skSkillsRegion.select():
+ *  base64 content has no '<', so the first </div> after the open tag is the real close.
+ *  STRICT data-rwa-frozen attribute-NAME check (mirror of the trust-read extractRwaSkillsZone):
+ *  refuse to write into an editable lookalike `<div id="rwa-skills">` BEFORE any write, so the
+ *  caller gets a clean no_skill_zone (exit 2) instead of a stray inert splice + a later
+ *  durability throw. The kind gate already restricts to skill-host; this is defence in depth. */
+function locateZone(doc) {
+  const open = /<div\b[^>]*\bid="rwa-skills"[^>]*>/i.exec(doc);
+  if (!open || !tagHasFrozenAttr(open[0])) return null;
+  const close = doc.indexOf('</div>', open.index + open[0].length);
+  if (close < 0) return null;
+  return { start: open.index, innerStart: open.index + open[0].length, innerEnd: close, end: close + 6 };
+}
+
+/** The FULL existing envelopes in the zone (parseSkillZone returns projections only — we need
+ *  the envelopes to merge). Malformed blocks are skipped (never block siblings). */
+function zoneEnvelopes(doc) {
+  const z = locateZone(doc);
+  if (!z) return null;
+  const out = [];
+  for (const m of doc.slice(z.innerStart, z.innerEnd).matchAll(SKILL_BLOCK_RE)) {
+    try { out.push(JSON.parse(Buffer.from(m[1].trim(), 'base64').toString('utf8'))); } catch { /* skip */ }
+  }
+  return out;
+}
+
+/** Non-blocking lookalike scan — mirror of the seed runtimeReviewSkill (seeds/rewritable.html
+ *  ~6700-6706): a DIFFERENT author key bearing an exact (d===0) or near (Levenshtein 1-2, both
+ *  names ≥4 chars) name is impersonation. The trust anchor is the KEY, not the name (Invariant
+ *  10), so this only WARNS — install still proceeds (Invariant 23, non-blocking). */
+function scanLookalike(existing, skill) {
+  for (const e of existing) {
+    const es = e.skill || {};
+    const d = levenshtein(es.name, skill.name);
+    const exact = d === 0;
+    const near = d >= 1 && d <= 2 && String(skill.name).length >= 4 && String(es.name).length >= 4;
+    if (es.author_pubkey !== skill.author_pubkey && (exact || near)) return es.name;
+  }
+  return null;
+}
+
+/** I5 (v0.9 §4) — Unicode-confusable (skeleton) scan. Catches homoglyph squatting that ASCII
+ *  Levenshtein misses: a name whose RFC 7954 skeleton folds (≤1 edit) to a DIFFERENT author's
+ *  installed name renders identically to a human. Returns the matched installed name or null.
+ *  The discriminator is `skeleton < normalized-Levenshtein`: confusable folding must have
+ *  COLLAPSED a real byte difference (cross-script glyphs). An honest ASCII near-miss (skeleton ==
+ *  Levenshtein) is NOT a homoglyph — it stays the non-blocking Levenshtein warning (Invariant 10,
+ *  and the I5 acceptance: "ASCII exact name, diff key → warning, install allowed"). Same author
+ *  (a rebrand) never matches — restyling your own name is not impersonation. */
+function scanSkeleton(existing, skill) {
+  for (const e of existing) {
+    const es = e.skill || {};
+    if (es.author_pubkey === skill.author_pubkey) continue;
+    const sd = skeletonDistance(es.name, skill.name);
+    const ld = levenshtein(normalizeName(es.name), normalizeName(skill.name));
+    if (sd <= 1 && sd < ld) return es.name; // folding made them confusable → impersonation
+  }
+  return null;
+}
+
+/**
+ * Pure core: gate an envelope, merge it into the host's INLINE_DOC zone, return the new doc body.
+ * No file I/O — installSkillFile owns that.
+ * @returns {{ newDoc:string, result:object, changed:boolean }}
+ * @throws {CliError} 3 envelope_error (gates) · 1 usage_error (no consent) · 2 file_error (no zone)
+ */
+export function installEnvelopeIntoDoc(inlineDoc, envelope, { consent } = {}) {
+  if (!envelope || envelope.format !== 'rwa-skill/1' || !envelope.skill || typeof envelope.skill.name !== 'string') {
+    throw new CliError(3, 'malformed_envelope', {});
+  }
+  const skill = envelope.skill;
+  const { signed, verified } = verifyEnvelope(envelope);
+  // Trust gates FIRST and FINAL — a gate failure throws before the consent check, so --yes
+  // (or its absence) can never turn a refused skill into an installed one.
+  const gate = validateInstall(envelope, { signed, verified });
+  if (!gate.ok) throw new CliError(3, gate.errors[0], { errors: gate.errors });
+  const forbidden = codeForbidden(skill.code);
+  if (forbidden) throw new CliError(3, forbidden, {});
+  // Consent: no dialog to review in → an explicit --yes is the offline review signal.
+  if (!consent) throw new CliError(1, 'interactive_install_deferred', { skill: skill.name });
+
+  const existing = zoneEnvelopes(inlineDoc);
+  if (existing === null) throw new CliError(2, 'no_skill_zone', {}); // not a skill-host body
+  const id = skillId(skill.name, skill.author_pubkey);
+  // I5 (v0.9 §4) — Unicode-confusable HARD block. A signed skill (it carries capability to
+  // escalate) whose name skeleton-folds to a DIFFERENT author's installed skill is impersonation:
+  // refuse before any code is registered. Unsigned skills can't escalate → warn only (below).
+  const skeletonMatch = scanSkeleton(existing, skill);
+  if (skeletonMatch && signed) throw new CliError(3, 'lookalike_skeleton_blocked', { match: skeletonMatch });
+  const lookalike = scanLookalike(existing, skill) || skeletonMatch; // non-blocking warning (Inv 10/23)
+  // I5 — name_history (CLI: registry-derived, dateless). Names this author (same pubkey) has already
+  // published in the host's zone, other than the incoming one — surfaces a same-key rename heads-up.
+  const priorNames = [...new Set(existing
+    .filter((e) => (e.skill || {}).author_pubkey === skill.author_pubkey && (e.skill || {}).name !== skill.name)
+    .map((e) => e.skill.name))];
+  const prevIdx = existing.findIndex((e) => skillId(e.skill.name, e.skill.author_pubkey) === id);
+  const prev = prevIdx >= 0 ? existing[prevIdx] : null;
+
+  // Same id + byte-identical envelope → already installed, no write.
+  if (prev && JSON.stringify(prev) === JSON.stringify(envelope)) {
+    return { newDoc: inlineDoc, changed: false, result: { skillId: id, name: skill.name, kind: skill.kind, verified, provenance: 'installed', status: 'already_installed', lookalike, priorNames } };
+  }
+
+  const merged = prev ? existing.map((e, i) => (i === prevIdx ? envelope : e)) : existing.concat([envelope]);
+  const z = locateZone(inlineDoc);
+  const newDoc = inlineDoc.slice(0, z.start) + buildSkillZone(merged) + inlineDoc.slice(z.end);
+
+  let update;
+  if (prev) {
+    const oldP = Array.isArray(prev.skill.permissions) ? prev.skill.permissions : [];
+    const newP = Array.isArray(skill.permissions) ? skill.permissions : [];
+    const oS = new Set(oldP), nS = new Set(newP);
+    update = { isUpdate: true, added: newP.filter((p) => !oS.has(p)), removed: oldP.filter((p) => !nS.has(p)) };
+  }
+  return { newDoc, changed: true, result: { skillId: id, name: skill.name, kind: skill.kind, verified, provenance: 'installed', status: prev ? 'updated' : 'installed', lookalike, priorNames, ...(update ? { update } : {}) } };
+}
+
+/**
+ * Read an envelope + a skill-host container, gate + splice + write atomically, re-parse for durability.
+ * @returns {Promise<object>} { skillId, name, kind, verified, provenance, status, update? }
+ * @throws {CliError} 1 usage_error · 2 file_error · 3 envelope_error
+ */
+export async function installSkillFile(envPath, hostPath, { consent } = {}) {
+  let envText;
+  try { envText = await readFile(envPath, 'utf8'); }
+  catch (e) { throw new CliError(2, e && e.code === 'ENOENT' ? 'not_found' : 'read_error', { path: envPath, errno: e && e.code }); }
+  let hostBytes;
+  try { hostBytes = await readFile(hostPath, 'utf8'); }
+  catch (e) { throw new CliError(2, e && e.code === 'ENOENT' ? 'not_found' : 'read_error', { path: hostPath, errno: e && e.code }); }
+
+  let envelope;
+  try { envelope = JSON.parse(envText); }
+  catch { throw new CliError(3, 'invalid_json', { path: envPath }); }
+
+  let inlineDoc;
+  try { inlineDoc = extractInlineDoc(hostBytes); }
+  catch { throw new CliError(2, 'not_a_rewritable', { path: hostPath }); }
+
+  // Kind gate — only a skill-host carries the frozen skill zone (mirror of detectProductKind).
+  const km = hostBytes.match(/const PRODUCT_KIND = '([^']*)';/);
+  const kind = km ? km[1] : null;
+  if (kind !== 'skill-host') throw new CliError(2, 'wrong_kind', { kind, expected: 'skill-host' });
+
+  const { newDoc, changed, result } = installEnvelopeIntoDoc(inlineDoc, envelope, { consent });
+  if (changed) {
+    await atomicWrite(hostPath, replaceInlineDoc(hostBytes, newDoc));
+    // Durability re-parse — the bytes on disk must contain the verified skill (Rule 12).
+    let reread;
+    try { reread = await readFile(hostPath, 'utf8'); }
+    catch (e) { throw new CliError(2, 'install_not_durable', { skillId: result.skillId, message: e && e.message }); }
+    if (!parseSkillZone(extractInlineDoc(reread)).some((p) => p.skillId === result.skillId)) {
+      throw new CliError(2, 'install_not_durable', { skillId: result.skillId });
+    }
+  }
+  return result;
+}

package/src/skill-manifest.mjs

@@ -60,6 +60,33 @@ export function parsePermission(p) {
     if (value.length > 64 || !VAULT_NS.test(value)) throw new Error(`invalid vault namespace: ${value}`);
     return { tier, value };
   }
+  if (tier === 'bus') {
+    // §5 (I1): topic 1–96 chars, must start alphanumeric, charset [A-Za-z0-9:_./%-], and NOT
+    // a runtime-reserved prefix (rwa_/rwa:/skills:/workspace: are the substrate's own channels).
+    if (!value || value.length > 96 || !/^[A-Za-z0-9][A-Za-z0-9:_./%-]*$/.test(value) || /^(?:rwa[:_]|skills:|workspace:)/.test(value))
+      throw new Error(`invalid bus topic: ${value}`);
+    return { tier, value };
+  }
+  if (tier === 'fsa') {
+    // §6 (I3): relative OPFS scope — lowercase [a-z0-9_/-], start+end alphanumeric/underscore,
+    // ≤128 chars, no leading/trailing slash, no '.'/'..' (excluded by charset), not _rwa/-prefixed.
+    if (!value || value.length > 128 || /^_rwa(?:\/|$)/.test(value) || !/^[a-z0-9_](?:[a-z0-9_/-]*[a-z0-9_])?$/.test(value))
+      throw new Error(`invalid fsa scope: ${value}`);
+    return { tier, value };
+  }
+  if (tier === 'idb') {
+    // §7 (I4): store name ^[A-Za-z0-9_][A-Za-z0-9_-]{0,62}$ (≤64 octets, no wildcards); never a
+    // reserved rwa_* store, and never the vault store — distinct subcodes so the dialog can explain.
+    if (/^rwa_/.test(value)) throw new Error(value === 'rwa_vault' ? 'idb_vault_store_forbidden' : 'idb_reserved_store');
+    if (!/^[A-Za-z0-9_][A-Za-z0-9_-]{0,62}$/.test(value)) throw new Error(`invalid idb store: ${value}`);
+    return { tier, value };
+  }
+  if (tier === 'hook') {
+    // §9 (I8): lifecycle event, exact-match enum, no wildcards. An UNKNOWN event is treated as an
+    // unknown tier (unknown_permission_tier) per the spec, so install rejects it the same way.
+    if (value === 'on-commit' || value === 'on-open' || value === 'on-mode-change') return { tier, value };
+    throw new Error(`unknown_permission_tier: hook event ${value}`);
+  }
   throw new Error(`unknown_permission_tier: ${tier}`);
 }
 
@@ -103,15 +130,35 @@ export function permissionToProse(perm) {
     if (v === '*') return 'Read and write credentials stored under ANY vault namespace — every credential you have stored. Use only for vault administration.';
     return `Read and write credentials stored under \`${v}\`.`;
   }
+  if (s.startsWith('bus:')) {
+    return `Send and receive messages on the \`${s.slice(4)}\` channel shared with other rewritables on this machine.`;
+  }
+  if (s.startsWith('fsa:')) {
+    return `Read and write files under \`${s.slice(4)}\` in this document's private storage.`;
+  }
+  if (s.startsWith('idb:')) {
+    return `Read and write the \`${s.slice(4)}\` data store in this document's database.`;
+  }
+  if (s.startsWith('hook:')) {
+    const ev = s.slice(5);
+    const when = ev === 'on-commit' ? 'every time the document is saved' : ev === 'on-open' ? 'every time the document opens' : ev === 'on-mode-change' ? 'every time you switch modes' : ev;
+    return `Run automatically ${when} (no network or credential access).`;
+  }
   return s;
 }
 
 /** §3.7/E — the compound-risk callout when vault + network co-occur, else null. */
 export function compoundRisk(permissions) {
   const perms = Array.isArray(permissions) ? permissions : [];
-  const hasVault = perms.some(p => String(p).startsWith('vault:'));
-  const hasNetwork = perms.some(p => String(p).startsWith('network:'));
+  const has = (t) => perms.some(p => String(p).startsWith(t + ':'));
+  const hasVault = has('vault'), hasNetwork = has('network'), hasBus = has('bus'), hasFsa = has('fsa'), hasIdb = has('idb');
   if (hasVault && hasNetwork) return 'This skill can both read your stored credentials AND make network requests. A skill with this combination can send credentials to its allowed destination — intentionally or by mistake. Install only if you fully trust this author.';
+  if (hasBus && (hasVault || hasNetwork)) return `This skill can message other rewritables on this machine AND ${hasVault ? 'read your stored credentials' : 'make network requests'}. Together these let it coordinate a multi-step action across your workspace — intentionally or by mistake. Install only if you fully trust this author.`;
+  if ((hasFsa || hasIdb) && (hasNetwork || hasVault || hasBus)) {
+    const store = hasFsa ? 'read and write files in this document' : 'read and write this document\'s stored data';
+    const sink = hasNetwork ? 'make network requests' : hasVault ? 'read your stored credentials' : 'message other rewritables on this machine';
+    return `This skill can ${store} AND ${sink}. Together these let it move your local data off this document — intentionally or by mistake. Install only if you fully trust this author.`;
+  }
   return null;
 }
 
@@ -141,6 +188,143 @@ export function levenshtein(a, b) {
   return prev[n];
 }
 
+// I5 (v0.9 §4) — Unicode-confusable skeleton. NFKC + toLowerCase fold case, fullwidth forms,
+// ligatures, and mathematical-alphanumeric letters to ASCII; this baked table folds the
+// CROSS-SCRIPT homoglyphs NFKC leaves alone (Cyrillic, Greek, Armenian, a few Latin-extended).
+// Deliberately CURATED, not the full UTS #39 confusables.txt: every entry maps a non-ASCII
+// glyph that renders ~identically to an ASCII letter. ASCII→ASCII is NEVER folded (so legit
+// distinct names like "tool"/"toml" stay distinct — no false collisions). Extensible: add a row.
+// Keys are post-NFKC-lowercase codepoints. Mirror of the seed's _SK_CONFUSABLES.
+const CONFUSABLES = {
+  // Cyrillic → Latin
+  'а': 'a', 'е': 'e', 'о': 'o', 'р': 'p', 'с': 'c',
+  'у': 'y', 'х': 'x', 'к': 'k', 'ѕ': 's', 'і': 'i',
+  'ј': 'j', 'ԁ': 'd', 'һ': 'h', 'ԛ': 'q', 'ԝ': 'w',
+  'ѵ': 'v', 'ӏ': 'l', 'ɠ': 'g',
+  // Greek → Latin
+  'α': 'a', 'ο': 'o', 'ρ': 'p', 'ε': 'e', 'ι': 'i',
+  'κ': 'k', 'ν': 'v', 'υ': 'u', 'χ': 'x', 'τ': 't',
+  'ϲ': 'c', 'ϳ': 'j',
+  // Armenian → Latin
+  'օ': 'o', 'ո': 'n',
+  // Latin-extended / IPA homoglyphs NFKC leaves alone
+  'ı': 'i', 'ɑ': 'a', 'ɡ': 'g',
+};
+
+/** NFKC-fold + lowercase a name before any lookalike comparison (UTS #36). */
+export function normalizeName(s) {
+  return String(s == null ? '' : s).normalize('NFKC').toLowerCase();
+}
+
+/** Confusable skeleton: normalize, then map each homoglyph to its ASCII prototype.
+ *  Two names with an equal skeleton render identically to a human (the trust-anchor risk). */
+export function skeleton(s) {
+  let out = '';
+  for (const ch of normalizeName(s)) out += (CONFUSABLES[ch] || ch);
+  return out;
+}
+
+/** Edit distance between two names' skeletons. 0 = perfect homoglyph; ≤1 = homoglyph + one typo. */
+export function skeletonDistance(a, b) {
+  return levenshtein(skeleton(a), skeleton(b));
+}
+
+// ── I12 (v0.9 §12) — rwa-agent/1: a role-scoped, signed agent identity (role + system_prompt +
+// vault_namespace_set; NO code field). Parallels the skill canon; the seed mirrors this logic.
+const ROLE_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/; // ≤64, lowercase a-z0-9-_, leading alphanumeric
+
+/** Canonical agent manifest: stable-key-ordered over the signed fields; excludes the signature. */
+export function canonicalAgent(agent) {
+  const a = agent || {};
+  return JSON.stringify({
+    author_pubkey: a.author_pubkey ?? null,
+    description: a.description ?? null,
+    role: a.role ?? null,
+    system_prompt: a.system_prompt ?? null,
+    vault_namespace_set: Array.isArray(a.vault_namespace_set) ? a.vault_namespace_set : [],
+    version: a.version ?? null,
+  });
+}
+
+/** Agent signing message bytes = sha256(canonicalAgent). Agents have no code field. */
+export function agentSigningMessage(agent) {
+  return sha256(Buffer.from(enc.encode(canonicalAgent(agent))));
+}
+
+/** agentId = base64url(sha256(role ‖ 0x00 ‖ author_pubkey)). Same role from different keys differ. */
+export function agentId(role, authorPubkey) {
+  return sha256(Buffer.concat([Buffer.from(enc.encode(String(role))), NUL, Buffer.from(enc.encode(String(authorPubkey)))]))
+    .toString('base64url');
+}
+
+/** Ed25519 verify over agentSigningMessage. Mirrors verifyEnvelope; the seed uses async WebCrypto. */
+export function verifyAgentEnvelope(envelope) {
+  const sig = envelope && envelope.signature;
+  if (!sig) return { signed: false, verified: false };
+  const agent = envelope.agent || {};
+  try {
+    const raw = Buffer.from(agent.author_pubkey, 'base64');
+    const key = createPublicKey({ key: Buffer.concat([ED25519_SPKI_PREFIX, raw]), format: 'der', type: 'spki' });
+    const verified = edVerify(null, agentSigningMessage(agent), key, Buffer.from(sig, 'base64'));
+    return { signed: true, verified: !!verified };
+  } catch {
+    return { signed: true, verified: false };
+  }
+}
+
+// A system_prompt is a runtime literal — reject anything that could break out of the template or
+// inject document markers (backtick, ${, <DOC>/<\/DOC>) → agent_prompt_injection_risk.
+function agentPromptInjectionRisk(s) {
+  const p = String(s ?? '');
+  return p.includes('`') || p.includes('${') || /<\/?DOC>/i.test(p);
+}
+
+/** §12 agent install gates. Pure; takes the verification result so it stays synchronous. */
+export function validateAgentInstall(envelope, { signed, verified } = {}) {
+  const agent = (envelope && envelope.agent) || {};
+  const errors = [];
+  // A NUL in the role makes agentId(role‖0x00‖pubkey) ambiguous — reject (mirrors F8).
+  if (/\0/.test(String(agent.role == null ? '' : agent.role))) errors.push('invalid_agent_id');
+  if (typeof agent.role !== 'string' || !ROLE_RE.test(agent.role)) errors.push('invalid_role');
+  // A missing/non-string OR injection-bearing prompt is rejected under the same gate.
+  if (typeof agent.system_prompt !== 'string' || agentPromptInjectionRisk(agent.system_prompt)) errors.push('agent_prompt_injection_risk');
+  const set = agent.vault_namespace_set;
+  if (set != null && !Array.isArray(set)) errors.push('invalid_permission');
+  for (const p of (Array.isArray(set) ? set : [])) {
+    try {
+      if (parsePermission(p).tier !== 'vault') errors.push('invalid_permission'); // vault_namespace_set is vault-only
+    } catch (e) {
+      errors.push(/unknown_permission_tier/.test(e.message) ? 'unknown_permission_tier' : 'invalid_permission');
+    }
+  }
+  if (!signed) errors.push('unsigned_agent'); // unsigned agents are rejected at install (verified gates activation)
+  return { ok: errors.length === 0, errors };
+}
+
+// §12 inter-agent bus message: {type:'request'|'response', id, from_role, to_role, payload} on
+// agents:* topics. Data-model only — the request→response choreography (wait/timeout) is the
+// conductor's responsibility, correlated by `id` (the requester's UUID, echoed by the responder).
+export function validateAgentMessage(m) {
+  const errors = [];
+  m = m || {};
+  if (m.type !== 'request' && m.type !== 'response') errors.push('invalid_type');
+  if (typeof m.id !== 'string' || !m.id) errors.push('invalid_id');
+  if (typeof m.from_role !== 'string' || !ROLE_RE.test(m.from_role)) errors.push('invalid_from_role');
+  if (typeof m.to_role !== 'string' || !ROLE_RE.test(m.to_role)) errors.push('invalid_to_role');
+  if (!('payload' in m)) errors.push('missing_payload');
+  return { ok: errors.length === 0, errors };
+}
+
+/** Build (and validate) an inter-agent bus message envelope. Throws invalid_agent_message if the
+ *  shape is bad. The caller supplies the correlation id (a fresh UUID for a request; the request's
+ *  id echoed for a response). */
+export function agentMessage(type, fromRole, toRole, payload, id) {
+  const m = { type, id, from_role: fromRole, to_role: toRole, payload };
+  const v = validateAgentMessage(m);
+  if (!v.ok) throw new Error('invalid_agent_message: ' + v.errors.join(','));
+  return m;
+}
+
 /** §3.4 install gates. Pure; takes the verification result so it stays synchronous. */
 export function validateInstall(envelope, { signed, verified } = {}) {
   const skill = (envelope && envelope.skill) || {};
@@ -153,11 +337,20 @@ export function validateInstall(envelope, { signed, verified } = {}) {
   if (/\0/.test(String(skill.name == null ? '' : skill.name))) errors.push('invalid_skill_id');
   for (const p of perms) {
     try { parsePermission(p); }
-    catch (e) { errors.push(/unknown_permission_tier/.test(e.message) ? 'unknown_permission_tier' : 'invalid_permission'); }
+    catch (e) {
+      const m = e.message;
+      if (/unknown_permission_tier/.test(m)) errors.push('unknown_permission_tier');
+      else if (m === 'idb_reserved_store' || m === 'idb_vault_store_forbidden') errors.push(m); // §7 distinct subcodes
+      else errors.push('invalid_permission');
+    }
   }
   if (skill.kind === 'compute' && perms.length > 0) errors.push('compute_with_permissions');
+  // §9 (I8): a hook is compute-only — only hook:<event> perms are allowed; any other tier (a real
+  // capability) is rejected as compute_with_permissions (no network/vault/escalation in a hook).
+  if (skill.kind === 'hook' && perms.some((p) => { try { return parsePermission(p).tier !== 'hook'; } catch { return false; } })) errors.push('compute_with_permissions');
   if (!signed && perms.length > 0) errors.push('unsigned_with_permissions');
-  if (skill.kind === 'tool' && !verified) errors.push('unsigned_capability');
+  // Tools AND hooks carry capability (a hook runs autonomously on events) → must be signed+verified.
+  if ((skill.kind === 'tool' || skill.kind === 'hook') && !verified) errors.push('unsigned_capability');
   return { ok: errors.length === 0, errors };
 }
 
@@ -225,3 +418,38 @@ export function parseSkillZone(doc) {
   }
   return out;
 }
+
+/** Locate the frozen `<div data-rwa-frozen id="rwa-agents">` zone (mirrors extractRwaSkillsZone). */
+function extractRwaAgentsZone(doc) {
+  const open = /<div\b[^>]*\bid="rwa-agents"[^>]*>/i.exec(String(doc || ''));
+  if (!open || !tagHasFrozenAttr(open[0])) return null;
+  const start = open.index + open[0].length;
+  const end = doc.indexOf('</div>', start);
+  return end < 0 ? null : doc.slice(start, end);
+}
+
+/** §12 / SD-04: parse installed agents from the frozen zone, re-verify each signature. Returns
+ *  [{agentId, kind:'agent', name:role, verified, provenance:'installed'}] — an installed agent is
+ *  an affordance the container offers (a role you can act under), mirroring parseSkillZone. */
+export function parseAgentZone(doc) {
+  const zone = extractRwaAgentsZone(doc);
+  if (!zone) return [];
+  const blocks = [...zone.matchAll(/<script\s+type="application\/rwa-agent\+json">([\s\S]*?)<\/script>/g)];
+  const out = [];
+  for (const m of blocks) {
+    let envelope;
+    try { envelope = JSON.parse(Buffer.from(m[1].trim(), 'base64').toString('utf8')); }
+    catch { continue; } // malformed block → skip (never blocks siblings)
+    const agent = envelope && envelope.agent;
+    if (!agent || typeof agent.role !== 'string') continue;
+    const { verified } = verifyAgentEnvelope(envelope);
+    out.push({
+      agentId: agentId(agent.role, agent.author_pubkey),
+      kind: 'agent',
+      name: agent.role,
+      verified,
+      provenance: 'installed',
+    });
+  }
+  return out;
+}