@cluesmith/codev 3.3.0 → 3.3.2

package/skeleton/protocols/air/protocol.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "../../protocol-schema.json",
+  "$schema": "../protocol-schema.json",
   "name": "air",
   "version": "1.0.0",
   "description": "AIR: Autonomous Implement & Review — lightweight protocol for small features from GitHub Issues",

package/skeleton/protocols/aspir/protocol.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "../../protocol-schema.json",
+  "$schema": "../protocol-schema.json",
   "name": "aspir",
   "version": "1.0.0",
   "description": "ASPIR: Autonomous SPIR — Specify → Plan → Implement → Review without human approval gates",
@@ -8,6 +8,10 @@
     "required": false,
     "default_for": ["--project", "-p"]
   },
+  "context_refresh": {
+    "on_enter": ["plan", "implement", "review"],
+    "on_plan_phase_advance": true
+  },
   "phases": [
     {
       "id": "specify",

package/skeleton/protocols/bugfix/protocol.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "../../protocol-schema.json",
+  "$schema": "../protocol-schema.json",
   "name": "bugfix",
   "version": "1.2.0",
   "description": "Lightweight protocol for minor bugfixes using GitHub Issues",

package/skeleton/protocols/experiment/protocol.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "../../protocol-schema.json",
+  "$schema": "../protocol-schema.json",
   "name": "experiment",
   "version": "1.0.0",
   "description": "Disciplined experimentation with hypothesis testing",

package/skeleton/protocols/maintain/protocol.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "../../protocol-schema.json",
+  "$schema": "../protocol-schema.json",
   "name": "maintain",
   "alias": "maint",
   "version": "3.0.0",

package/skeleton/protocols/pir/builder-prompt.md

@@ -42,8 +42,9 @@ the code directly in the worktree (you see it via `git diff`), typing into your
 `afx send <your-builder-id>` (queued — check next turn), or a comment on the GitHub issue
 (re-fetch with `gh issue view <N> --comments`).
 
-Revise, recommit, ask whether more remains. **The gate stays pending until the human runs
-`porch approve` — never call it yourself.**
+Revise, recommit, ask whether more remains. **The gate stays pending until the human approves. When
+the architect relays that approval, run `porch approve <id> <gate> --a-human-explicitly-approved-this`
+to record it and continue — never on your own initiative.**
 
 ## Resumption After Crash
 

package/skeleton/protocols/pir/prompts/implement.md

@@ -140,7 +140,7 @@ Then **stay in the interactive session**. Do not exit. Wait for the user's next
 
 - **Don't write `codev/reviews/<id>-<slug>.md` in this phase** — it's the next phase's artifact, with a different shape (retrospective with arch + lessons updates)
 - Don't add features not in the plan — scope creep is a `BLOCKED` signal, not a free expansion
-- Don't run `porch approve` yourself
+- Don't run `porch approve` on your own initiative — only when the architect relays the human's approval
 - Don't push to the default branch — only to your builder branch
 - Don't squash commits — let the merge commit preserve history
 - Don't open the PR yet — that's the `review` phase

package/skeleton/protocols/pir/prompts/plan.md

@@ -114,7 +114,7 @@ Then **stay in the interactive session**. Do not exit. Wait for the user's next
 ## What NOT to Do
 
 - Don't write code — that's the implement phase
-- Don't run `porch approve` yourself — only the human can approve the gate
+- Don't run `porch approve` on your own initiative — only when the architect relays the human's approval
 - Don't post the plan content as a GitHub issue comment — the plan lives in the file, not the issue thread. A one-line pointer comment on the issue is fine if you think it helps the discussion.
 - Don't exit the interactive session at the gate
 

package/skeleton/protocols/pir/prompts/review.md

@@ -240,7 +240,7 @@ Together with the `--pr` record from step 4a and the `--merged` record from step
 
 - **Don't merge before the `pr` gate is approved** (steps 8–9). Neither a consultation APPROVE verdict nor user-in-pane prose ("looks good", "lgtm", "merge it") authorizes `gh pr merge` — only porch reporting `gate_status: approved` for the `pr` gate does.
 - Don't skip porch's PR/merge records (steps 4a, 9). The `--pr` record (step 4a) lets the gate-pending state link to the actual PR; the `--merged` record (step 9) closes the lifecycle in porch state. Skipping either leaves `history:` empty and downstream tooling blind.
-- Don't run `porch approve` for any gate yourself
+- Don't run `porch approve` for any gate on your own initiative — only when the architect relays the human's approval
 - Don't push to the default branch — only merge via PR
 - Don't skip the Architecture Updates / Lessons Learned sections — porch checks enforce their presence (the section must exist; explaining "no changes needed" in one line is fine)
 - **Don't run `consult` commands yourself** — porch handles consultations via the `verify` block. Manually invoking `consult` causes the consultation to run twice.

package/skeleton/protocols/pir/protocol.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "../../protocol-schema.json",
+  "$schema": "../protocol-schema.json",
   "name": "pir",
   "alias": "plan-implement-review",
   "version": "1.0.0",

package/skeleton/protocols/pir/protocol.md

@@ -32,14 +32,14 @@ protocol is safe and needs no porch change.
 | `dev-approval` | pre-PR | **PIR's distinctive gate** — reviews the *running* worktree via `afx dev` |
 | `pr` | post-PR | Reviews on GitHub, then approves; porch wakes the builder to merge |
 
-The `pr` gate makes the merge trigger **structured porch state** rather than free text in the
-builder's pane — closing the self-merge class where a builder infers authorization from
-ambiguous prose.
+The `pr` gate holds the merge behind porch state: the human approves, the architect relays that
+approval, and the builder records it with `porch approve pr` before porch hands over the merge task.
 
 **Gates do not notify the architect automatically.** Porch broadcasts `overview-changed` over
 SSE; the VSCode Builders tree renders the blocked state with a bell and raises a toast. CLI
 users see it via the builder pane or `porch pending`. The builder's job at any gate is: write
-the artifact, commit, signal, wait — never to invoke `porch approve` itself.
+the artifact, commit, signal, wait — then run `porch approve` when the architect relays the human's
+approval, never on your own initiative.
 
 ## Rejection is iteration, not a command
 

package/skeleton/protocols/protocol-schema.json

@@ -33,6 +33,23 @@
     "hooks": {
       "$ref": "#/definitions/protocolHooks"
     },
+    "context_refresh": {
+      "type": "object",
+      "description": "Boundaries at which builders automatically refresh their context (Spec 1470). Absent means no refreshes.",
+      "additionalProperties": false,
+      "properties": {
+        "on_enter": {
+          "type": "array",
+          "description": "Protocol phase ids to refresh on entry to. Each must name a phase this protocol declares.",
+          "uniqueItems": true,
+          "items": { "type": "string" }
+        },
+        "on_plan_phase_advance": {
+          "type": "boolean",
+          "description": "Refresh when advancing from one plan phase to the next. Requires a 'per_plan_phase' phase. Excludes the first plan phase, which coincides with entering the phase itself."
+        }
+      }
+    },
     "signals": {
       "type": "object",
       "description": "Signal definitions for state transitions",

package/skeleton/protocols/research/protocol.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "../../protocol-schema.json",
+  "$schema": "../protocol-schema.json",
   "name": "research",
   "version": "1.0.0",
   "description": "Multi-agent research with 3-way investigation, synthesis, and critique",

package/skeleton/protocols/spike/protocol.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "../../protocol-schema.json",
+  "$schema": "../protocol-schema.json",
   "name": "spike",
   "version": "1.0.0",
   "description": "Time-boxed technical feasibility exploration",

package/skeleton/protocols/spir/protocol.json

@@ -1,5 +1,5 @@
 {
-  "$schema": "../../protocol-schema.json",
+  "$schema": "../protocol-schema.json",
   "name": "spir",
   "alias": "spider",
   "version": "2.2.0",
@@ -9,6 +9,10 @@
     "required": false,
     "default_for": ["--project", "-p"]
   },
+  "context_refresh": {
+    "on_enter": ["plan", "implement", "review"],
+    "on_plan_phase_advance": true
+  },
   "phases": [
     {
       "id": "specify",

package/skeleton/resources/commands/agent-farm.md

@@ -501,12 +501,12 @@ afx send 0042 "That producer died — stop waiting and report."
 
 ---
 
-### afx reset
+### afx refresh
 
-Reset a builder's context: have it save its working state, clear the conversation, then re-orient it.
+Refresh a builder's context: have it save its working state, clear the conversation, then re-orient it.
 
 ```bash
-afx reset <builder> [options]
+afx refresh <builder> [options]
 ```
 
 **Arguments:**
@@ -522,10 +522,13 @@ afx reset <builder> [options]
 - `--min-bytes <n>` - Minimum state-file size to accept as substantive (default 1000)
 - `--quiet-window <ms>` - Terminal silence that counts as turn-ended (default 1500)
 
+**Deprecated alias:** `afx reset` still runs this command and prints a one-line notice to stderr.
+It will be removed in a future release — use `afx refresh`.
+
 **Description:**
 
 Long-running builders exhaust their context window. `afx spawn --resume` reattaches the *same*
-conversation, so a deep session resumes deep — it does not give the builder a fresh window. `afx reset`
+conversation, so a deep session resumes deep — it does not give the builder a fresh window. `afx refresh`
 does, without losing what the builder knows.
 
 The sequence:
@@ -533,7 +536,7 @@ The sequence:
 1. Assemble the re-orientation and write it to `.builder-reorient.md` in the worktree.
 2. Ask the builder to write its complete working state to `.builder-state.md`, stamped with a one-time
    nonce.
-3. Wait for that file and **verify** it: correct nonce (not a stale file from an earlier reset),
+3. Wait for that file and **verify** it: correct nonce (not a stale file from an earlier refresh),
    substantive size, and stable across two observations (not still being written).
 4. Wait for the terminal to fall silent, so the clear is not typed mid-turn. If it does not settle, send
    **one** ESC and wait again.
@@ -556,19 +559,19 @@ then `afx spawn <id> --resume`).
 
 ```bash
 # See exactly what would be sent, without touching the builder
-afx reset 0042 --dry-run
+afx refresh 0042 --dry-run
 
-# Standard reset
-afx reset 0042
+# Standard refresh
+afx refresh 0042
 
 # Add context that post-dates the builder's saved state
-afx reset 0042 --note "PR #90 merged while you were mid-phase. Rebase before continuing."
+afx refresh 0042 --note "PR #90 merged while you were mid-phase. Rebase before continuing."
 
 # The builder is wedged mid-turn and not reading messages
-afx reset 0042 --interrupt-first
+afx refresh 0042 --interrupt-first
 
 # A builder that legitimately needs longer to write its state
-afx reset 0042 --timeout 600
+afx refresh 0042 --timeout 600
 ```
 
 ---

package/skeleton/roles/builder.md

@@ -23,9 +23,8 @@ say so, **stop**, and wait.
 Never treat a porch gate as approved without an explicit human decision — a gate message is a notification to the human, not authorization.
 
 Approval reaches you as a message from the architect. Then *you* run
-`porch approve <id> <gate>`; the architect does not run it for you — **unless your protocol's
-prompts route that command to the human instead** (PIR's gates are typed by the human reviewer,
-via Cmd+K G or their own shell). Defer to your protocol's phase prompts on who types `porch approve`.
+`porch approve <id> <gate>`; the architect does not run it for you. Defer to your protocol's phase
+prompts on who types `porch approve`.
 
 ## Deliverables
 
@@ -72,7 +71,7 @@ nobody can redirect, and you will not notice, because from inside it everything
 Never chain foreground poll loops.
 
 If you are wedged anyway, the architect can end your turn with `afx interrupt <your-id>`, or
-`afx reset <your-id>` to have you save state and re-orient. Worth knowing so you can suggest
+`afx refresh <your-id>` to have you save state and re-orient. Worth knowing so you can suggest
 them.
 
 ## PRs

package/templates/3d-viewer.html

@@ -218,12 +218,18 @@
     </div>
   </div>
 
-  <!-- Three.js ES Modules via import map -->
+  <!-- Three.js ES Modules — vendored locally (three@0.160.0), served same-origin
+       from the annotator's vendor/ route. NO remote code runs in this page: it is
+       key-injected (advisory GHSA-xvjp-7748-v88v), so loading executable modules
+       from a CDN would expose window.__CODEV_TOWER_KEY__ to that CDN. -->
   <script type="importmap">
   {
     "imports": {
-      "three": "https://cdn.jsdelivr.net/npm/three@0.160.0/build/three.module.js",
-      "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.160.0/examples/jsm/"
+      "three": "vendor/three.module.js",
+      "three/addons/loaders/STLLoader.js": "vendor/three-STLLoader.js",
+      "three/addons/loaders/3MFLoader.js": "vendor/three-3MFLoader.js",
+      "three/addons/controls/TrackballControls.js": "vendor/three-TrackballControls.js",
+      "fflate": "vendor/three-fflate.module.js"
     }
   }
   </script>
@@ -234,6 +240,24 @@
     import { ThreeMFLoader } from 'three/addons/loaders/3MFLoader.js';
     import { TrackballControls } from 'three/addons/controls/TrackballControls.js';
 
+    // Request authentication (advisory GHSA-xvjp-7748-v88v): Tower injects the
+    // shared local key into this page same-origin; model/mtime requests send it
+    // via the codev-tower-key header. Three.js loaders carry it through
+    // loader.setRequestHeader(authHeaders()).
+    function getWebKey() {
+      if (window.__CODEV_TOWER_KEY__) {
+        try { localStorage.setItem('codev-tower-key', window.__CODEV_TOWER_KEY__); } catch (e) {}
+        return window.__CODEV_TOWER_KEY__;
+      }
+      return localStorage.getItem('codev-tower-key');
+    }
+    function authHeaders(extra) {
+      const key = getWebKey();
+      const headers = extra ? Object.assign({}, extra) : {};
+      if (key) headers['codev-tower-key'] = key;
+      return headers;
+    }
+
     // Configuration (injected by server with proper escaping)
     const FILE_PATH = {{FILE_PATH_JSON}};  // JSON-encoded by server
     const FILE_NAME = '{{FILE}}';
@@ -370,6 +394,7 @@
 
     function loadSTL() {
       const loader = new STLLoader();
+      loader.setRequestHeader(authHeaders());
 
       loader.load(
         'api/model',
@@ -412,6 +437,7 @@
 
     function load3MF() {
       const loader = new ThreeMFLoader();
+      loader.setRequestHeader(authHeaders());
 
       loader.load(
         'api/model',
@@ -715,7 +741,7 @@
 
     async function checkForChanges() {
       try {
-        const res = await fetch('api/mtime');
+        const res = await fetch('api/mtime', { headers: authHeaders() });
         if (res.ok) {
           const data = await res.json();
           if (lastMtime === null) {
@@ -769,6 +795,7 @@
 
     function reloadSTL() {
       const loader = new STLLoader();
+      loader.setRequestHeader(authHeaders());
       loader.load('api/model?t=' + Date.now(), (geometry) => {
         // Center geometry in XY
         geometry.computeBoundingBox();
@@ -811,6 +838,7 @@
 
     function reload3MF() {
       const loader = new ThreeMFLoader();
+      loader.setRequestHeader(authHeaders());
       loader.load('api/model?t=' + Date.now(), (group) => {
         // 3MF uses Z-up natively, which matches our coordinate system
 

package/templates/open.html

@@ -569,6 +569,51 @@
   <script src="vendor/prism-markup.min.js"></script>
 
   <script>
+    // Request authentication (advisory GHSA-xvjp-7748-v88v): Tower injects the
+    // shared local key into this page same-origin; every data/media fetch sends
+    // it via the codev-tower-key header. Media is fetched as an authenticated blob
+    // (img/video/pdf src cannot carry a header) and displayed via an object URL,
+    // revoked when replaced or on unload to avoid blob leaks.
+    function getWebKey() {
+      if (window.__CODEV_TOWER_KEY__) {
+        try { localStorage.setItem('codev-tower-key', window.__CODEV_TOWER_KEY__); } catch (e) {}
+        return window.__CODEV_TOWER_KEY__;
+      }
+      return localStorage.getItem('codev-tower-key');
+    }
+    function authHeaders(extra) {
+      const key = getWebKey();
+      const headers = extra ? Object.assign({}, extra) : {};
+      if (key) headers['codev-tower-key'] = key;
+      return headers;
+    }
+    function setMediaSrc(el, objectUrl) {
+      if (el.__objUrl) URL.revokeObjectURL(el.__objUrl);
+      el.__objUrl = objectUrl;
+      el.src = objectUrl;
+    }
+    async function loadMedia(el, path) {
+      try {
+        const res = await fetch(path, { headers: authHeaders() });
+        if (!res.ok) throw new Error('status ' + res.status);
+        const blob = await res.blob();
+        setMediaSrc(el, URL.createObjectURL(blob));
+      } catch (e) {
+        if (typeof el.onerror === 'function') el.onerror();
+      }
+    }
+    function revokeAllMediaUrls() {
+      ['image-display', 'video-display', 'pdf-display'].forEach(function(id) {
+        const el = document.getElementById(id);
+        if (el && el.__objUrl) URL.revokeObjectURL(el.__objUrl);
+      });
+    }
+    // pagehide fires on mobile / bfcache navigations where beforeunload does not.
+    // Skip revocation when the page is going into the bfcache (persisted): the
+    // object URLs must survive so restored media still renders on pageshow.
+    window.addEventListener('pagehide', function(e) { if (!e.persisted) revokeAllMediaUrls(); });
+    window.addEventListener('beforeunload', revokeAllMediaUrls);
+
     // State
     let fileLines = [];
     let currentLine = null;
@@ -673,8 +718,8 @@
         img.style.display = 'none';
       };
 
-      // Add cache-busting query param to allow reload
-      img.src = 'api/image?t=' + Date.now();
+      // Fetch as an authenticated blob (img.src cannot carry the key header).
+      loadMedia(img, 'api/image?t=' + Date.now());
     }
 
     // Initialize video viewer
@@ -707,8 +752,8 @@
         video.style.display = 'none';
       };
 
-      // Add cache-busting query param to allow reload
-      video.src = 'api/video?t=' + Date.now();
+      // Fetch as an authenticated blob (video.src cannot carry the key header).
+      loadMedia(video, 'api/video?t=' + Date.now());
     }
 
     // Initialize PDF viewer
@@ -726,9 +771,10 @@
       const pdfViewer = document.getElementById('pdf-viewer');
       pdfViewer.style.display = 'block';
 
-      // Load PDF via raw endpoint
+      // Load PDF via raw endpoint as an authenticated blob (embed.src cannot
+      // carry the key header).
       const embed = document.getElementById('pdf-display');
-      embed.src = 'api/pdf?t=' + Date.now();
+      loadMedia(embed, 'api/pdf?t=' + Date.now());
     }
 
     // Update image info display (in both header and controls)
@@ -1339,7 +1385,7 @@
       try {
         const response = await fetch('save', {
           method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
+          headers: authHeaders({ 'Content-Type': 'application/json' }),
           body: JSON.stringify({
             file: filePath,
             content: fileLines.join('\n')
@@ -1457,7 +1503,7 @@
       try {
         const response = await fetch('save', {
           method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
+          headers: authHeaders({ 'Content-Type': 'application/json' }),
           body: JSON.stringify({ file: filePath, content })
         });
 
@@ -1778,7 +1824,7 @@
       if (hasUnsavedChanges || editMode) return;
 
       try {
-        const res = await fetch('api/mtime');
+        const res = await fetch('api/mtime', { headers: authHeaders() });
         if (res.ok) {
           const data = await res.json();
           if (lastMtime === null) {
@@ -1797,21 +1843,21 @@
       // For images and videos, just reload the source
       if (isImageFile) {
         const img = document.getElementById('image-display');
-        img.src = 'api/image?t=' + Date.now();
+        loadMedia(img, 'api/image?t=' + Date.now());
         showNotification('Image reloaded');
         return;
       }
 
       if (isVideoFile) {
         const video = document.getElementById('video-display');
-        video.src = 'api/video?t=' + Date.now();
+        loadMedia(video, 'api/video?t=' + Date.now());
         showNotification('Video reloaded');
         return;
       }
 
       // For text files, fetch new content
       try {
-        const res = await fetch('file');
+        const res = await fetch('file', { headers: authHeaders() });
         if (res.ok) {
           const content = await res.text();
           currentContent = content;

package/templates/tower.html

@@ -8,6 +8,7 @@
   <meta name="theme-color" content="#252525">
   <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>🗼</text></svg>">
   <title>Agent Farm Tower</title>
+  <!-- CODEV_TOWER_KEY_INJECTION -->
   <style>
     * {
       box-sizing: border-box;
@@ -989,21 +990,39 @@
     let runningInstances = [];
     let recentInstances = [];
 
-    // Auth helper: get headers with auth token if available
+    // Auth helper: resolve the shared local key. Prefer the value Tower injects
+    // same-origin at serve time (window.__CODEV_TOWER_KEY__); fall back to any
+    // previously stored value. The injected value is persisted so later loads
+    // and manual navigations keep working.
+    function getWebKey() {
+      if (window.__CODEV_TOWER_KEY__) {
+        try { localStorage.setItem('codev-tower-key', window.__CODEV_TOWER_KEY__); } catch (e) {}
+        return window.__CODEV_TOWER_KEY__;
+      }
+      return localStorage.getItem('codev-tower-key');
+    }
+
+    // Auth helper: get headers with the auth key if available
     function getAuthHeaders() {
-      const key = localStorage.getItem('codev-web-key');
-      return key ? { 'Authorization': `Bearer ${key}` } : {};
+      const key = getWebKey();
+      return key ? { 'codev-tower-key': key } : {};
     }
 
     // Auth helper: make authenticated fetch request
     async function authFetch(url, options = {}) {
+      const hadKey = !!getWebKey();
       const headers = { ...getAuthHeaders(), ...(options.headers || {}) };
       const response = await fetch(url, { ...options, headers });
 
-      // If 401, clear key and redirect to login
+      // If 401, clear a now-stale key. Only reload when we actually sent a key:
+      // a reload re-fetches the shell and picks up a freshly injected key. With
+      // no key to begin with, the shell has none to inject, so reloading would
+      // loop forever (advisory GHSA-xvjp-7748-v88v) — surface the error instead.
       if (response.status === 401) {
-        localStorage.removeItem('codev-web-key');
-        location.reload();
+        localStorage.removeItem('codev-tower-key');
+        if (hadKey) {
+          location.reload();
+        }
         throw new Error('Unauthorized');
       }
       return response;
@@ -1011,7 +1030,7 @@
 
     // Logout function
     function logout() {
-      localStorage.removeItem('codev-web-key');
+      localStorage.removeItem('codev-tower-key');
       window.location.href = './';
     }