@sugar-crash-studios/vibe-forge 0.4.0

package/tasks/completed/PLAT-1-heimdall.md

@@ -0,0 +1,420 @@
+---
+id: PLAT-1
+title: "Heimdall -- forge worker pre-tool hook interceptor"
+type: security
+priority: high
+status: pending
+assigned_to: null
+epic: PLAT
+estimated_complexity: medium
+depends_on: []
+blocked_by: []
+created: 2026-04-01T00:00:00-05:00
+lab_story_id: null
+---
+
+# Context
+
+## Why This Exists
+
+Forge workers running in background daemon mode use `--dangerously-skip-permissions`.
+In terminal tab mode, a human can observe and intervene. In unattended background mode
+there is no runtime human gate.
+
+Heimdall is the compensating control. It intercepts every tool call before it executes,
+checks it against per-task policy, and blocks or allows with an audit log entry.
+
+Named for the Norse watchman of the gods. The Gjallarhorn escalation is the signal that
+something has gone wrong and a human must intervene.
+
+## Architecture Reference
+
+`docs/architecture/vibe-lab-integration.md` -- Security Model section
+
+---
+
+# Acceptance Criteria
+
+1. Heimdall is registered as a `PreToolUse` hook in `.claude/settings.local.json`
+   written by the forge daemon to each worker's working directory at startup
+2. Every hard-block category listed below returns exit `2` with a clear message
+3. Every audit-log category is allowed (exit `0`) and appended to the daemon log
+4. Context file (`.context.json`) is read on every invocation -- policy is
+   per-task, not global
+5. After N violations in a single task (default 3, configurable), Heimdall writes
+   `{story-id}.escalation` signal file and logs `HEIMDALL SOUNDED`
+6. Forge daemon detects `.escalation` file and writes escalation handoff
+7. All existing forge tests pass -- no regression on forge-native tasks
+8. Heimdall exits `0` immediately when no context file is present (forge-native
+   tasks without a `.context.json` are not restricted by Heimdall)
+
+---
+
+# Tasks / Subtasks
+
+## 1. `bin/lib/heimdall.js` -- core interceptor
+
+```javascript
+#!/usr/bin/env node
+// Heimdall -- PreToolUse hook for forge workers running in lab pipeline
+// Reads tool call from stdin, checks policy, exits 0 (allow) or 2 (block)
+
+import { readFileSync, existsSync, appendFileSync, writeFileSync } from 'fs'
+import { join, resolve } from 'path'
+
+const input = JSON.parse(readFileSync('/dev/stdin', 'utf8'))
+const { tool_name, tool_input } = input
+
+// Locate context file -- written by forge daemon alongside the inbox task
+// Convention: .context.json in the working directory
+const contextPath = join(process.cwd(), '.context.json')
+
+// No context file = forge-native task, not a lab pipeline task
+// Heimdall does not restrict forge-native work
+if (!existsSync(contextPath)) {
+  process.exit(0)
+}
+
+const ctx = JSON.parse(readFileSync(contextPath, 'utf8'))
+const { story_id, agent, worktree_path, handoff_dir, has_db_migration, allowed_paths } = ctx
+
+const AUDIT_LOG = join(process.env.FORGE_DAEMON_LOG || process.cwd(), 'heimdall-audit.log')
+const VIOLATION_FILE = join(process.cwd(), `${story_id}.violations`)
+const MAX_VIOLATIONS = parseInt(process.env.HEIMDALL_MAX_VIOLATIONS || '3', 10)
+
+function timestamp() {
+  return new Date().toISOString()
+}
+
+function audit(level, message) {
+  const line = `[${timestamp()}] HEIMDALL ${level} ${agent}/${story_id}: ${message}\n`
+  appendFileSync(AUDIT_LOG, line)
+}
+
+function block(reason) {
+  audit('BLOCKED', reason)
+
+  // Track violation count
+  let violations = 0
+  if (existsSync(VIOLATION_FILE)) {
+    violations = parseInt(readFileSync(VIOLATION_FILE, 'utf8').trim(), 10) || 0
+  }
+  violations++
+  writeFileSync(VIOLATION_FILE, String(violations))
+
+  if (violations >= MAX_VIOLATIONS) {
+    const escalationFile = join(process.cwd(), `${story_id}.escalation`)
+    writeFileSync(escalationFile, JSON.stringify({
+      story_id, agent, violations, reason, timestamp: timestamp()
+    }))
+    audit('SOUNDED', `${violations} violations, escalating to human review`)
+    console.log(
+      `[HEIMDALL] Action blocked: ${reason}\n` +
+      `[HEIMDALL] GJALLARHORN SOUNDED: ${violations} violations. Story escalated to human review.`
+    )
+  } else {
+    console.log(
+      `[HEIMDALL] Action blocked: ${reason}\n` +
+      `[HEIMDALL] Violation ${violations}/${MAX_VIOLATIONS}. Self-correct and continue.`
+    )
+  }
+
+  process.exit(2)
+}
+
+function allow(note) {
+  if (note) audit('ALLOWED', note)
+  process.exit(0)
+}
+
+function isOutsideAllowedPaths(targetPath) {
+  const resolved = resolve(targetPath)
+  return !allowed_paths.some(p => resolved.startsWith(resolve(p)))
+}
+
+// ── BASH tool checks ────────────────────────────────────────────────────────
+if (tool_name === 'Bash') {
+  const cmd = (tool_input.command || '').trim()
+
+  // Catastrophic filesystem operations
+  if (/rm\s+-[a-zA-Z]*r[a-zA-Z]*f|rm\s+-[a-zA-Z]*f[a-zA-Z]*r/.test(cmd)) {
+    // rm -rf or rm -fr -- check if target is outside worktree
+    const rmTarget = cmd.replace(/rm\s+-\S+\s+/, '').trim()
+    if (!rmTarget || isOutsideAllowedPaths(rmTarget) ||
+        /^(\/|~|\.\.)/.test(rmTarget.replace(/^['"]|['"]$/g, ''))) {
+      block(`destructive rm targeting outside worktree: ${cmd}`)
+    }
+  }
+
+  // Credential access
+  if (/\.(env|pem|key|cert)\b/.test(cmd) ||
+      /~\/\.(ssh|aws)/.test(cmd) ||
+      /TOKEN|SECRET|PASSWORD|API_KEY/i.test(cmd) && /echo|print|cat|export\s+\w+=/.test(cmd)) {
+    block(`credential access attempt: ${cmd}`)
+  }
+
+  // Dangerous git operations
+  if (/git\s+push\s+.*--force/.test(cmd)) block(`force push blocked: ${cmd}`)
+  if (/git\s+reset\s+--hard\s+HEAD~[2-9]/.test(cmd)) block(`multi-commit reset blocked: ${cmd}`)
+  if (/git\s+clean\s+-[a-zA-Z]*f[a-zA-Z]*d/.test(cmd)) block(`git clean -fd blocked: ${cmd}`)
+  if (/git\s+push\s+(?!origin\b)/.test(cmd)) block(`push to non-origin remote blocked: ${cmd}`)
+
+  // DB operations without authorization
+  if (/(DROP\s+TABLE|TRUNCATE\s+TABLE)/i.test(cmd) && !has_db_migration) {
+    block(`DROP/TRUNCATE requires has_db_migration: true in story submission`)
+  }
+  if (/DELETE\s+FROM\s+\w+\s*;/i.test(cmd)) {
+    block(`DELETE without WHERE clause blocked: ${cmd}`)
+  }
+
+  // High-risk but legitimate -- audit log only
+  if (/npm\s+install|pip\s+install|cargo\s+build|yarn\s+add/.test(cmd)) {
+    allow(`dependency install: ${cmd}`)
+  }
+  if (/curl|wget/.test(cmd)) {
+    allow(`network request: ${cmd}`)
+  }
+  if (/git\s+commit\s+--amend/.test(cmd)) {
+    allow(`git commit --amend`)
+  }
+}
+
+// ── WRITE / EDIT tool checks ────────────────────────────────────────────────
+if (tool_name === 'Write' || tool_name === 'Edit') {
+  const filePath = tool_input.file_path || tool_input.path || ''
+
+  // Credential files
+  if (/\.(env|pem|key|cert)$/.test(filePath)) {
+    block(`write to credential file blocked: ${filePath}`)
+  }
+
+  // Path escape -- must be in allowed paths
+  if (filePath && isOutsideAllowedPaths(filePath)) {
+    block(`path escape: ${filePath} is outside allowed paths`)
+  }
+
+  // Writes to handoff/inbox dirs -- allowed but logged
+  if (filePath.includes('_vibe-chain-output')) {
+    allow(`pipeline output write: ${filePath}`)
+  }
+}
+
+// All other tools -- allow by default
+allow(null)
+```
+
+## 2. Context file schema
+
+Written by the forge daemon to `_vibe-chain-output/worker-inbox/<agent>/{story-id}.context.json`
+alongside each inbox task file. Heimdall reads this on every invocation.
+
+```json
+{
+  "story_id": "FORGE-3",
+  "agent": "furnace",
+  "worktree_path": "/abs/path/to/worktree",
+  "assigned_branch": "feature/forge-3-events-api",
+  "handoff_dir": "/abs/path/to/_vibe-chain-output/handoffs",
+  "has_db_migration": false,
+  "has_api_changes": true,
+  "allowed_paths": [
+    "/abs/path/to/worktree",
+    "/abs/path/to/_vibe-chain-output/handoffs",
+    "/abs/path/to/_vibe-chain-output/worker-inbox"
+  ]
+}
+```
+
+All paths must be absolute. The forge daemon resolves them from `project_root` at inbox-write time.
+
+## 3. `settings.local.json` written by daemon at worker startup
+
+The forge daemon must write (or merge) this into `.claude/settings.local.json` in the
+worker's working directory when starting a worker for a lab task. This installs Heimdall
+for that worker session.
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [{ "type": "command", "command": "node bin/lib/heimdall.js" }]
+      },
+      {
+        "matcher": "Write",
+        "hooks": [{ "type": "command", "command": "node bin/lib/heimdall.js" }]
+      },
+      {
+        "matcher": "Edit",
+        "hooks": [{ "type": "command", "command": "node bin/lib/heimdall.js" }]
+      }
+    ]
+  }
+}
+```
+
+Use a merge strategy: if `.claude/settings.local.json` already exists, merge the hooks
+array rather than overwrite. Preserve any existing hooks the worker session already has.
+
+**Implementation:** `bin/lib/daemon/heimdall-setup.js` -- called by the daemon at inbox-write time.
+
+## 4. Escalation signal handling in forge daemon
+
+The daemon's task monitoring loop (in `forge-daemon.sh` or the modularized equivalent)
+must check for `.escalation` files:
+
+```bash
+check_heimdall_escalations() {
+    local inbox_dir="$1"
+    for escalation_file in "$inbox_dir"/**/*.escalation; do
+        [[ -f "$escalation_file" ]] || continue
+        local story_id
+        story_id=$(basename "$escalation_file" .escalation)
+        local agent_dir
+        agent_dir=$(dirname "$escalation_file")
+        local agent
+        agent=$(basename "$agent_dir")
+
+        log "HEIMDALL SOUNDED: $agent/$story_id -- writing escalation handoff"
+
+        # Write escalation handoff to lab's handoff directory
+        # Lab sentinel will route to human review on next cycle
+        write_escalation_handoff "$story_id" "$agent" "$escalation_file"
+
+        # Move escalation file to processed
+        mv "$escalation_file" "${escalation_file}.processed"
+    done
+}
+```
+
+The escalation handoff format:
+```yaml
+---
+type: worker-escalation
+story: "{story_id}"
+from: forge-daemon
+to: human
+created: {ISO8601}
+status: pending
+agent: "{agent}"
+violations: {N}
+---
+
+## Heimdall Escalation
+
+Worker `{agent}` accumulated {N} policy violations on story `{story_id}`.
+The worker has been stopped for this story. Human review required.
+
+## Last Violation
+{reason from .escalation JSON}
+
+## Action Required
+Review the audit log at `heimdall-audit.log` and decide:
+- Fix the story spec and resubmit
+- Manually complete the work
+- Cancel the story
+```
+
+## 5. Configuration
+
+Add to `_vibe-chain/config.yaml` under `agent_personalities`:
+
+```yaml
+agent_personalities:
+  heimdall:
+    enabled: true           # always on when agent_personalities is configured
+    max_violations: 3       # violations before Gjallarhorn
+    audit_log: _vibe-chain-output/heimdall-audit.log
+```
+
+## 6. Tests (`tests/heimdall.test.js`)
+
+```javascript
+import { describe, test, expect } from '@jest/globals'
+// Test by invoking heimdall.js as a subprocess with mocked stdin and context file
+
+describe('Heimdall -- hard blocks', () => {
+  test('blocks rm -rf outside worktree', async () => {
+    const result = await runHeimdall(
+      { tool_name: 'Bash', tool_input: { command: 'rm -rf /tmp/other' } },
+      { worktree_path: '/tmp/worktree', allowed_paths: ['/tmp/worktree'] }
+    )
+    expect(result.exitCode).toBe(2)
+    expect(result.stdout).toContain('destructive rm')
+  })
+
+  test('blocks force push', async () => {
+    const result = await runHeimdall(
+      { tool_name: 'Bash', tool_input: { command: 'git push origin --force' } },
+      baseContext()
+    )
+    expect(result.exitCode).toBe(2)
+  })
+
+  test('blocks path escape on Write', async () => {
+    const result = await runHeimdall(
+      { tool_name: 'Write', tool_input: { file_path: '/etc/passwd' } },
+      baseContext()
+    )
+    expect(result.exitCode).toBe(2)
+    expect(result.stdout).toContain('path escape')
+  })
+
+  test('blocks DROP TABLE without has_db_migration', async () => {
+    const result = await runHeimdall(
+      { tool_name: 'Bash', tool_input: { command: 'sqlite3 app.db "DROP TABLE users"' } },
+      { ...baseContext(), has_db_migration: false }
+    )
+    expect(result.exitCode).toBe(2)
+  })
+
+  test('allows DROP TABLE with has_db_migration', async () => {
+    const result = await runHeimdall(
+      { tool_name: 'Bash', tool_input: { command: 'sqlite3 app.db "DROP TABLE old_schema"' } },
+      { ...baseContext(), has_db_migration: true }
+    )
+    expect(result.exitCode).toBe(0)
+  })
+})
+
+describe('Heimdall -- audit log allows', () => {
+  test('allows npm install with audit entry', async () => {
+    const result = await runHeimdall(
+      { tool_name: 'Bash', tool_input: { command: 'npm install lodash' } },
+      baseContext()
+    )
+    expect(result.exitCode).toBe(0)
+    // Audit log should contain the entry -- checked via log file
+  })
+})
+
+describe('Heimdall -- forge-native passthrough', () => {
+  test('exits 0 immediately when no context file present', async () => {
+    const result = await runHeimdall(
+      { tool_name: 'Bash', tool_input: { command: 'rm -rf /' } },
+      null  // no context file
+    )
+    expect(result.exitCode).toBe(0)
+  })
+})
+
+describe('Heimdall -- escalation', () => {
+  test('writes .escalation file after N violations', async () => {
+    // Run N blocking actions, check .escalation exists on Nth
+  })
+})
+```
+
+---
+
+# Notes
+
+- Heimdall must be fast. It runs on every tool call. Target < 50ms per invocation.
+  Read context file once per process start (it is passed as a singleton call).
+  Do not make network calls.
+- The `bin/lib/heimdall.js` path in the hook command must be absolute or resolvable
+  from the worker's working directory. Use `process.env.FORGE_BIN_DIR` if needed.
+- PLAT-1 is a prerequisite for IPC-7 (background worker daemon mode).
+  It also applies to LAB-FORGE-3 (degraded spawn) -- LAB-FORGE-3 must write
+  `.claude/settings.local.json` at spawn time, same as IPC workers.

package/tasks/completed/SEC-001-sql-injection-fix.md

@@ -0,0 +1,58 @@
+---
+id: SEC-001
+title: Fix SQL Injection vulnerabilities in database.sh
+type: security
+priority: critical
+status: completed
+assigned_to: aegis
+created_at: 2026-01-15T16:30:00Z
+created_by: security-review
+completed_at: 2026-01-15T17:30:00Z
+completed_by: aegis
+---
+
+## Summary
+
+Multiple SQLite queries in `bin/lib/database.sh` interpolate shell variables directly into SQL strings without proper escaping or parameterization.
+
+## Affected Lines
+
+- Line 93: `db_set_daemon_state()` - `$new_state` interpolated
+- Lines 136-145: `db_upsert_agent_status()` - `$agent`, `$status`, `$task`, `$message`, `$updated_at` interpolated
+- Line 151: `db_get_agent_mtime()` - `$agent` interpolated
+- Line 166: `db_get_agents_by_status()` - `$status` interpolated
+
+## Attack Scenario
+
+A malicious agent status JSON file could contain:
+```json
+{"agent": "'; DROP TABLE agent_status; --", "status": "working"}
+```
+
+## Remediation Applied
+
+1. Created `db_escape()` function that:
+   - Removes null bytes
+   - Escapes single quotes by doubling them (`'` -> `''`)
+   - Removes backslashes that could escape quotes
+
+2. Created `db_validate_identifier()` for validating identifiers
+
+3. Applied `db_escape()` to all user-controlled variables in:
+   - `db_upsert_agent_status()` - all string parameters
+   - `db_get_agent_mtime()` - agent parameter
+   - `db_get_agents_by_status()` - status parameter
+   - `db_record_status_history()` - all parameters
+
+4. Added numeric validation for:
+   - `file_mtime` in `db_upsert_agent_status()`
+   - `minutes` in `db_cleanup_stale_agents()`
+   - `days` in `db_prune_history()`
+
+5. Added whitelist validation for `db_set_daemon_state()` - only allows `active|idle|stopped`
+
+## Acceptance Criteria
+
+- [x] All SQL queries use escaped or parameterized inputs
+- [x] Numeric parameters validated before use
+- [x] State values whitelist-validated

package/tasks/completed/SEC-002-notification-injection-fix.md

@@ -0,0 +1,45 @@
+---
+id: SEC-002
+title: Fix Command Injection in system notifications
+type: security
+priority: critical
+status: completed
+assigned_to: aegis
+created_at: 2026-01-15T16:30:00Z
+created_by: security-review
+completed_at: 2026-01-15T17:30:00Z
+completed_by: aegis
+---
+
+## Summary
+
+The `send_system_notification()` function in `bin/forge-daemon.sh` directly interpolates `$message` into PowerShell and osascript commands without sanitization.
+
+## Affected Lines
+
+- Lines 146-154: Windows PowerShell - `$message` in CreateTextNode()
+- Line 158: macOS osascript - `$message` in display notification
+
+## Attack Scenario
+
+Malicious task file:
+```yaml
+title: "'); Start-Process calc; #"
+```
+
+When extracted and passed to notification, executes arbitrary commands.
+
+## Remediation Applied
+
+1. Created `sanitize_notification_message()` function that:
+   - Removes null bytes
+   - Strips all characters except: alphanumeric, spaces, periods, commas, colons, semicolons, exclamation/question marks, hyphens, underscores
+   - Limits message length to 200 characters
+
+2. Applied sanitization in `send_system_notification()` before any shell interpolation
+
+## Acceptance Criteria
+
+- [x] All notification messages sanitized before shell interpolation
+- [x] Special characters stripped
+- [x] Notifications still display readable messages (safe chars preserved)

package/tasks/completed/SEC-003-eval-injection-fix.md

@@ -0,0 +1,54 @@
+---
+id: SEC-003
+title: Fix eval injection in agent config loading
+type: security
+priority: high
+status: completed
+assigned_to: aegis
+created_at: 2026-01-15T16:30:00Z
+created_by: security-review
+completed_at: 2026-01-15T17:30:00Z
+completed_by: aegis
+---
+
+## Summary
+
+The `load_agents_from_json()` function in `bin/lib/config.sh` uses `eval` to execute shell variable assignments generated from JSON file contents.
+
+## Affected Lines
+
+- Line 100: `eval "$agent_data"`
+
+## Attack Scenario
+
+Malicious `config/agents.json`:
+```json
+{
+  "agents": {
+    "anvil$(whoami>/tmp/pwned)": {
+      "name": "Anvil"
+    }
+  }
+}
+```
+
+Command substitution executes when `eval` runs.
+
+## Remediation Applied
+
+1. Added `isValidIdentifier()` function in Node.js that validates names match `^[a-z0-9_-]+$`
+
+2. Added `escapeForShell()` function that escapes dangerous characters in string values:
+   - Backslashes, double quotes, dollar signs, backticks, newlines
+
+3. All agent names and aliases are validated before output:
+   - Invalid names cause immediate exit with clear error message
+
+4. All string values (display names, roles, icons, etc.) are escaped before output
+
+## Acceptance Criteria
+
+- [x] Agent names validated to alphanumeric + underscore/hyphen only
+- [x] Special characters in agents.json cause clear error, not execution
+- [x] Existing valid configurations continue to work
+- [x] String values properly escaped for shell safety

package/tasks/completed/SEC-004-pid-race-condition-fix.md

@@ -0,0 +1,49 @@
+---
+id: SEC-004
+title: Fix TOCTOU race condition in PID file handling
+type: security
+priority: high
+status: completed
+assigned_to: aegis
+created_at: 2026-01-15T16:30:00Z
+created_by: security-review
+completed_at: 2026-01-15T17:30:00Z
+completed_by: aegis
+---
+
+## Summary
+
+The daemon start logic in `bin/forge-daemon.sh` has a Time-of-Check-Time-of-Use (TOCTOU) race condition between checking if the daemon is running and writing the new PID file.
+
+## Affected Lines
+
+- Lines 541-565: `cmd_start()` - race window between check and PID write
+
+## Attack Scenario
+
+Two simultaneous `forge daemon start` commands could both pass the initial check, leading to:
+- Multiple daemon instances
+- PID file corruption
+- Unpredictable behavior
+
+## Remediation Applied
+
+1. Added flock-based exclusive locking at the start of `cmd_start()`:
+   - Creates `startup.lock` file in `.forge/` directory
+   - Uses file descriptor 200 for the lock
+   - Non-blocking lock attempt (`flock -n`)
+   - Lock automatically released when script exits
+
+2. Graceful fallback when flock is not available:
+   - Falls back to existing PID-based check (less secure but functional)
+   - Maintains cross-platform compatibility
+
+3. Defense in depth:
+   - Existing LOCK_FILE check remains as secondary protection
+
+## Acceptance Criteria
+
+- [x] Use flock or equivalent for atomic lock acquisition
+- [x] Only one daemon instance can start at a time
+- [x] Lock released properly on daemon exit (automatic via fd close)
+- [x] Works on Windows (Git Bash), macOS, Linux (with fallback)

package/tasks/completed/SEC-005-worker-loop-path-fix.md

@@ -0,0 +1,51 @@
+---
+id: SEC-005
+title: Fix path traversal in worker-loop hook
+type: security
+priority: high
+status: completed
+assigned_to: aegis
+created_at: 2026-01-15T16:30:00Z
+created_by: security-review
+completed_at: 2026-01-15T17:30:00Z
+completed_by: aegis
+---
+
+## Summary
+
+The worker-loop hook in `.claude/hooks/worker-loop.sh` defaults `FORGE_ROOT` to the current working directory without validation.
+
+## Affected Lines
+
+- Line 20: `FORGE_ROOT="${FORGE_ROOT:-$(pwd)}"`
+
+## Attack Scenario
+
+If the hook executes in an attacker-controlled directory (e.g., `/tmp/malicious`), task file checks could be redirected:
+```
+FORGE_ROOT=/tmp/malicious
+$TASKS_DIR="/tmp/malicious/tasks"
+```
+
+Attacker could place malicious task files that get processed.
+
+## Remediation Applied
+
+1. If FORGE_ROOT is set via environment:
+   - Validate it contains `.forge/` or `tasks/` directory
+   - Reject with safe JSON response if validation fails
+
+2. If FORGE_ROOT is not set:
+   - Derive from script location (`.claude/hooks/` -> `../..`)
+   - Validate derived path contains expected directories
+   - Fall back to pwd only if it passes validation
+
+3. Safe failure mode:
+   - Returns `{"decision": "allow"}` with error message on validation failure
+   - Does not process potentially malicious task directories
+
+## Acceptance Criteria
+
+- [x] FORGE_ROOT validated before use
+- [x] Hook fails safely if run from invalid directory
+- [x] Normal operation unaffected when run correctly