@cluesmith/codev 3.3.4 → 3.3.5

package/skeleton/protocols/protocol-schema.json

@@ -133,6 +133,12 @@
           "type": "string",
           "description": "Command to run"
         },
+        "timeout_ms": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 2147483647,
+          "description": "Kill the check after this many milliseconds (default: 300000, i.e. 5 minutes)"
+        },
         "on_fail": {
           "type": "string",
           "description": "Action on failure: 'retry' or phase name to return to"

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

@@ -932,6 +932,50 @@ afx spawn 42 --protocol spir --builder-cmd "claude --model haiku"
 
 Both are Tower-global (they apply to the whole Tower, not per-project) and optional — omit them to use the defaults above.
 
+### Decisions tab
+
+When a workspace has a pending-decisions file, the dashboard shows a **Decisions** tab (Spec 1819). The tab is a view of that file. Each item under `## Open` becomes a card with a click box per option (the first option, the recommended one, is marked) and a comment box. Submitting writes the chosen word, then the comment, on the lines right after the item's `**Your word:**` line, exactly as the owner would type them, and changes nothing else. `## Ruled` is shown below as a collapsed, read-only list. The file is the only state. While the tab is open it re-reads the file every 2 seconds, so edits made elsewhere appear without a reload, and an unsent draft survives them.
+
+The file is `codev/state/pending-decisions.md` unless `dashboard.decisionsFile` names another:
+
+```json
+{
+  "dashboard": {
+    "decisionsFile": "codev/state/pending-decisions.md"
+  }
+}
+```
+
+- **Relative to the workspace root.** An absolute path, or anything but a non-empty string, is a configuration error: the tab does not appear, and Tower logs the error once.
+- **Inside the workspace.** The path is resolved with symlinks followed on every read and write, and a path that leads outside the workspace (directly, through `..`, or through a symlink) is refused. A symlinked decisions file keeps its link: the ruling is written to its in-workspace target.
+- **Layers.** Like the other settings, it can be set globally in `~/.codev/config.json`, for the team in the project's `.codev/config.json`, or per engineer in `.codev/config.local.json`. Project settings override global ones, and project-local settings override both.
+
+The tab appears once the file exists (within about 5 seconds of a change to the setting), and then stays for the page session: if the file is deleted while the tab is open, the tab says so and keeps any unsent draft. A reload of a workspace without the file shows no tab. A submit is refused, with a message on the card and the draft kept, when the item has changed or been ruled since the tab showed it. Tower applies one write to a file at a time and replaces the file atomically (a temporary file renamed over it).
+
+After each ruling is written, Tower tells the workspace's hub architect, the one named `main`, in one mailbox message delivered like an `afx send architect`: `RULED <id>: <word>`, or `QUESTION <id>:` for a comment-only submit, with the comment on the lines after it, under a `[USER via Decisions tab]` header. Like any message it waits for a clear prompt, and it waits for `main` to come back if `main` is not running. A workspace with no architect named `main` gets no notice: Tower logs a warning naming the workspace and does not pick another architect. A failed send is logged and leaves the ruling as written: the file is still the source of truth, and a ruling typed into the file by hand reaches the hub only when it scans the file.
+
+### Porch check overrides
+
+Protocol checks default to the npm toolchain (`npm run build`, `npm test`). Override them per check name under `porch.checks` instead of forking `protocol.json`:
+
+```json
+{
+  "porch": {
+    "checks": {
+      "build": { "command": "cargo build" },
+      "tests": { "command": "cargo test", "timeout_ms": 900000 },
+      "e2e_tests": { "skip": true }
+    }
+  }
+}
+```
+
+**Override fields:**
+- `command` — Replace the protocol's check command with a custom shell command
+- `cwd` — Override the working directory for this check (relative to project root)
+- `timeout_ms` — Kill the check after this many milliseconds (default 5 minutes; a protocol.json check can set it too). On timeout porch kills the check's whole process tree
+- `skip: true` — Omit this check entirely (for checks that don't apply to your project)
+
 ---
 
 ## Files

package/skeleton/resources/commands/consult.md

@@ -366,8 +366,8 @@ agy   # run once and sign in (OAuth / Google subscription)
 ```
 
 Configure auth:
-- Claude: `ANTHROPIC_API_KEY`
-- Codex: `OPENAI_API_KEY`
+- Claude: the stored `claude` login, or `CLAUDE_CODE_OAUTH_TOKEN` / `ANTHROPIC_API_KEY`
+- Codex: the stored `codex login`, or `CODEX_API_KEY` (codex ignores `OPENAI_API_KEY`)
 - Gemini (`agy`): **OAuth / subscription** — run `agy` once and sign in (no API key). If `agy`
   is missing or unauthenticated, the gemini lane skips non-blockingly (the run proceeds without it).
 
@@ -434,6 +434,13 @@ The Agent SDK otherwise prioritizes `ANTHROPIC_API_KEY`, which silently routes
 CMAP/review traffic to the metered API (issue #985). When no OAuth token is set,
 the API key is used as before so CI / key-only environments keep working.
 
+**Workspace `.env` (issue #1754).** `consult` loads `<workspace>/.env` and sets every key the
+shell does not already define, credentials included. So a `CLAUDE_CODE_OAUTH_TOKEN` there
+overrides your stored login and, via the strip above, displaces the API key too; `CODEX_API_KEY`
+does the same for codex. Each SDK lane logs what it authenticates with, e.g.
+`[CLAUDE] auth: CLAUDE_CODE_OAUTH_TOKEN (from .env)`. A result the SDK flags as an error (usage
+limit, billing, auth) fails the run with no output file, and the error names that credential.
+
 > **Caveat:** dedicated Agent-SDK subscription credit starts **2026-06-15**.
 > Before that date, subscription auth draws from the interactive Max quota.
 

package/skeleton/templates/cheatsheet.md

@@ -61,7 +61,7 @@ A **protocol** is a structured workflow that defines how work progresses from id
 | Protocol | Use For | Phases |
 |----------|---------|--------|
 | **SPIR** | New features | Specify → Plan → Implement → Review |
-| **MAINTAIN** | Codebase hygiene | Dead code removal, documentation sync |
+| **MAINTAIN** | Scheduled codebase hygiene | Whole-repo audit → clean → sync run since the last one, on the human's call. Not for a single targeted cleanup or doc fix (that is a BUGFIX) |
 | **EXPERIMENT** | Research & prototyping | Hypothesis → Experiment → Conclude |
 | **RESEARCH** | Multi-agent research | Scope → Investigate (3-way) → Synthesize → Critique (3-way) |