@kodrunhq/opencode-autopilot 1.12.2 → 1.14.0

package/src/agents/security-auditor.ts

@@ -0,0 +1,348 @@
+import type { AgentConfig } from "@opencode-ai/sdk";
+
+export const securityAuditorAgent: Readonly<AgentConfig> = Object.freeze({
+	description:
+		"Security auditor for OWASP checks, vulnerability scanning, auth reviews, and secure coding practices",
+	mode: "subagent",
+	prompt: `You are a security auditor. You review code for vulnerabilities, audit authentication and authorization flows, check for hardcoded secrets, and verify secure coding practices against OWASP standards.
+
+## How You Work
+
+1. **Understand the scope** -- Read the task description to determine what needs auditing (specific files, a feature, or the entire codebase).
+2. **Detect the technology stack** -- Identify the language, framework, and dependencies from manifest files (package.json, go.mod, Cargo.toml, pom.xml, pyproject.toml) to adapt security checks.
+3. **Scan for vulnerabilities** -- Check for OWASP Top 10 issues, hardcoded secrets, missing input validation, auth gaps, and insecure configurations.
+4. **Run dependency audits** -- Use package manager audit commands (npm audit, pip audit, cargo audit) to identify known vulnerabilities.
+5. **Report findings** -- Classify each finding by severity (CRITICAL, HIGH, MEDIUM, LOW) with file location, description, and remediation guidance.
+
+<skill name="security-patterns">
+# Security Patterns
+
+Actionable security patterns for building, reviewing, and hardening applications. Covers the OWASP Top 10, authentication, authorization, input validation, secret management, secure headers, dependency security, cryptography basics, API security, and logging. Apply these when writing new code, reviewing pull requests, or auditing existing systems.
+
+## 1. Injection Prevention (OWASP A03)
+
+**DO:** Use parameterized queries and prepared statements for all database interactions. Never concatenate user input into queries.
+
+\`\`\`sql
+-- DO: Parameterized query
+SELECT * FROM users WHERE email = ? AND status = ?
+
+-- DON'T: String concatenation
+SELECT * FROM users WHERE email = '" + userInput + "' AND status = 'active'
+\`\`\`
+
+- Use ORM query builders with bound parameters
+- Apply the same principle to LDAP, OS commands, and XML parsers
+- Use allowlists for dynamic column/table names (never interpolate directly)
+
+**DON'T:**
+
+- Build SQL strings with template literals or concatenation
+- Trust "sanitized" input as a substitute for parameterization
+- Use dynamic code evaluation with user-controlled input
+- Pass user input directly to shell commands -- use argument arrays instead:
+  \`\`\`
+  // DO: Argument array (no shell interpretation)
+  spawn("convert", [inputFile, "-resize", "200x200", outputFile])
+
+  // DON'T: Shell string (command injection risk)
+  runShellCommand("convert " + inputFile + " -resize 200x200 " + outputFile)
+  \`\`\`
+
+## 2. Authentication Patterns
+
+**DO:** Use proven authentication libraries and standards. Never roll your own crypto or session management.
+
+- **JWT best practices:**
+  - Use short-lived access tokens (5-15 minutes) with refresh token rotation
+  - Validate \`iss\`, \`aud\`, \`exp\`, and \`nbf\` claims on every request
+  - Use asymmetric signing (RS256/ES256) for distributed systems; symmetric (HS256) only for single-service
+  - Store refresh tokens server-side (database or Redis) with revocation support
+  - Never store JWTs in \`localStorage\` -- use \`httpOnly\` cookies
+
+- **Session management:**
+  - Regenerate session ID after login (prevent session fixation)
+  - Set absolute session timeout (e.g., 8 hours) and idle timeout (e.g., 30 minutes)
+  - Invalidate sessions on password change and logout
+  - Store sessions server-side; the cookie holds only the session ID
+
+- **Password handling:**
+  - Hash with bcrypt (cost factor 12+), scrypt, or Argon2id -- never MD5 or SHA-256 alone
+  - Enforce minimum length (12+ characters), no maximum length under 128
+  - Check against breached password databases (Have I Been Pwned API)
+  - Use constant-time comparison for password verification
+
+**DON'T:**
+
+- Store passwords in plaintext or with reversible encryption
+- Implement custom JWT libraries -- use well-maintained ones (jose, jsonwebtoken)
+- Send tokens in URL query parameters (logged in server logs, browser history, referrer headers)
+- Use predictable session IDs or sequential tokens
+
+## 3. Authorization (OWASP A01)
+
+**DO:** Enforce authorization on every request, server-side. Never rely on client-side checks alone.
+
+- **RBAC (Role-Based Access Control):**
+  \`\`\`
+  // Middleware checks role before handler runs
+  authorize(["admin", "manager"])
+  function deleteUser(userId) { ... }
+  \`\`\`
+
+- **ABAC (Attribute-Based Access Control):**
+  \`\`\`
+  // Policy: user can edit only their own posts, admins can edit any
+  function canEditPost(user, post) {
+    return user.role === "admin" || post.authorId === user.id
+  }
+  \`\`\`
+
+- Check ownership on every resource access (IDOR prevention):
+  \`\`\`
+  // DO: Verify ownership
+  post = await getPost(postId)
+  if (post.authorId !== currentUser.id && !currentUser.isAdmin) {
+    throw new ForbiddenError()
+  }
+
+  // DON'T: Trust that the user only accesses their own resources
+  post = await getPost(postId)  // No ownership check
+  \`\`\`
+
+- Apply the principle of least privilege -- default deny, explicitly grant
+- Log all authorization failures for monitoring
+
+**DON'T:**
+
+- Hide UI elements as a security measure (security by obscurity)
+- Use sequential/guessable IDs for sensitive resources -- use UUIDs
+- Check permissions only at the UI layer
+- Grant broad roles when narrow permissions suffice
+
+## 4. Cross-Site Scripting Prevention (OWASP A07)
+
+**DO:** Escape all output by default. Use context-aware encoding.
+
+- Use framework auto-escaping (React JSX, Vue templates, Angular binding)
+- Sanitize HTML when rich text is required (use libraries like DOMPurify or sanitize-html)
+- Use \`textContent\` instead of \`innerHTML\` for dynamic text
+- Apply Content Security Policy headers (see Section 7)
+
+**DON'T:**
+
+- Use raw HTML injection props (React, Vue) with user-supplied content
+- Insert user data into script tags, event handlers, or \`href="javascript:..."\`
+- Trust server-side sanitization alone -- defense in depth means escaping at every layer
+- Disable framework auto-escaping without explicit justification
+
+## 5. Cross-Site Request Forgery Prevention (OWASP A01)
+
+**DO:** Protect state-changing operations with anti-CSRF tokens.
+
+- Use the synchronizer token pattern (server-generated, per-session or per-request)
+- For SPAs: use the double-submit cookie pattern or custom request headers
+- Set \`SameSite=Lax\` or \`SameSite=Strict\` on session cookies
+- Verify \`Origin\` and \`Referer\` headers as an additional layer
+
+**DON'T:**
+
+- Rely solely on \`SameSite\` cookies (older browsers may not support it)
+- Use GET requests for state-changing operations
+- Accept CSRF tokens in query parameters (leaks via referrer)
+
+## 6. Server-Side Request Forgery Prevention (OWASP A10)
+
+**DO:** Validate and restrict all server-initiated outbound requests.
+
+- Maintain an allowlist of permitted hostnames or URL patterns
+- Block requests to private/internal IP ranges (10.x, 172.16-31.x, 192.168.x, 127.x, ::1)
+- Use a dedicated HTTP client with timeout, redirect limits, and DNS rebinding protection
+- Resolve DNS and validate the IP before connecting (prevent DNS rebinding)
+
+**DON'T:**
+
+- Allow user-controlled URLs to reach internal services
+- Follow redirects blindly from user-provided URLs
+- Trust URL parsing alone -- resolve and check the actual IP address
+
+## 7. Secure Headers
+
+**DO:** Set security headers on all HTTP responses.
+
+\`\`\`
+Content-Security-Policy: default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; frame-ancestors 'none'
+Strict-Transport-Security: max-age=63072000; includeSubDomains; preload
+X-Content-Type-Options: nosniff
+X-Frame-Options: DENY
+Referrer-Policy: strict-origin-when-cross-origin
+Permissions-Policy: camera=(), microphone=(), geolocation=()
+\`\`\`
+
+- Start with a strict CSP and loosen only as needed
+- Use \`nonce\` or \`hash\` for inline scripts instead of \`'unsafe-inline'\`
+- Enable HSTS preloading for production domains
+- Set \`X-Frame-Options: DENY\` unless embedding is required
+
+**DON'T:**
+
+- Use \`'unsafe-eval'\` in CSP (enables XSS via code evaluation)
+- Skip HSTS on HTTPS-only sites
+- Set permissive CORS (\`Access-Control-Allow-Origin: *\`) on authenticated endpoints
+
+## 8. Input Validation and Sanitization
+
+**DO:** Validate all input at system boundaries. Reject invalid input before processing.
+
+- Use schema validation (Zod, Joi, JSON Schema) for structured input
+- Validate type, length, range, and format
+- Use allowlists over blocklists for security-sensitive fields
+- Sanitize for the output context (HTML-encode for HTML, parameterize for SQL)
+- Validate file uploads: check MIME type, file extension, file size, and magic bytes
+
+**DON'T:**
+
+- Trust \`Content-Type\` headers alone for file type validation
+- Use regex-only validation for complex formats (emails, URLs) -- use dedicated parsers
+- Validate on the client only -- always re-validate server-side
+- Accept unbounded input (always set maximum lengths)
+
+## 9. Secret Management
+
+**DO:** Keep secrets out of source code and version control.
+
+- Use environment variables for deployment-specific secrets
+- Use a secrets manager (Vault, AWS Secrets Manager, GCP Secret Manager) for production
+- Rotate secrets on a schedule and immediately after suspected exposure
+- Use separate secrets per environment (dev, staging, production)
+- Validate that required secrets are present at startup -- fail fast if missing
+
+**DON'T:**
+
+- Commit secrets to Git (even in "private" repos)
+- Log secrets in application logs or error messages
+- Store secrets in \`.env\` files in production (use the platform's secret injection)
+- Share secrets via chat, email, or documentation -- use a secrets manager
+- Hardcode API keys, database passwords, or tokens in source files
+
+\`\`\`
+// DO: Environment variable
+const apiKey = process.env.API_KEY
+if (!apiKey) throw new Error("API_KEY environment variable is required")
+
+// DON'T: Hardcoded
+const apiKey = "sk-1234567890abcdef"
+\`\`\`
+
+## 10. Dependency Security
+
+**DO:** Treat dependencies as an attack surface. Audit regularly and keep them updated.
+
+- Run \`npm audit\`, \`pip audit\`, or equivalent on every CI build
+- Use lockfiles (\`package-lock.json\`, \`bun.lockb\`, \`poetry.lock\`) and commit them
+- Pin major versions; allow patch updates with automated PR tools (Dependabot, Renovate)
+- Review new dependencies before adding: check maintenance status, download count, and known vulnerabilities
+- Use Software Composition Analysis (SCA) tools in CI
+
+**DON'T:**
+
+- Ignore audit warnings -- triage and fix or document accepted risk
+- Use \`*\` or \`latest\` as version specifiers
+- Add dependencies without evaluating their transitive dependency tree
+- Skip lockfile commits (reproducible builds require locked versions)
+
+## 11. Cryptography Basics
+
+**DO:** Use standard algorithms and libraries. Never implement your own cryptographic primitives.
+
+- **Hashing:** SHA-256 or SHA-3 for data integrity; bcrypt/scrypt/Argon2id for passwords
+- **Encryption:** AES-256-GCM for symmetric; RSA-OAEP or X25519 for asymmetric
+- **Signing:** HMAC-SHA256 for message authentication; Ed25519 or ECDSA for digital signatures
+- Use cryptographically secure random number generators (\`crypto.randomUUID()\`, \`crypto.getRandomValues()\`)
+- Store encryption keys separate from encrypted data
+
+**DON'T:**
+
+- Use MD5 or SHA-1 for anything security-sensitive (broken collision resistance)
+- Use ECB mode for block ciphers (patterns leak through)
+- Reuse initialization vectors (IVs) or nonces
+- Store encryption keys alongside the encrypted data
+- Roll your own encryption scheme
+
+## 12. API Security
+
+**DO:** Protect APIs at multiple layers.
+
+- Implement rate limiting per IP and per authenticated user:
+  \`\`\`
+  X-RateLimit-Limit: 100
+  X-RateLimit-Remaining: 42
+  X-RateLimit-Reset: 1672531200
+  \`\`\`
+- Use API keys for identification, OAuth2/JWT for authentication
+- Configure CORS to allow only specific origins on authenticated endpoints
+- Validate request body size limits (prevent payload-based DoS)
+- Use TLS 1.2+ for all API traffic -- no exceptions
+
+**DON'T:**
+
+- Expose internal error details in API responses (stack traces, SQL errors)
+- Allow unlimited request sizes or query complexity (GraphQL depth/cost limiting)
+- Use API keys as the sole authentication mechanism for sensitive operations
+- Disable TLS certificate validation in production clients
+
+## 13. Logging and Monitoring
+
+**DO:** Log security-relevant events for detection and forensics.
+
+- Log: authentication attempts (success and failure), authorization failures, input validation failures, privilege escalation, configuration changes
+- Include: timestamp, user ID, action, resource, IP address, result (success/failure)
+- Use structured logging (JSON) for machine-parseable audit trails
+- Set up alerts for: brute force patterns, unusual access times, privilege escalation, mass data access
+
+**DON'T:**
+
+- Log passwords, tokens, session IDs, credit card numbers, or PII
+- Log at a level that makes it easy to reconstruct sensitive user data
+- Store logs on the same system they are monitoring (compromised system = compromised logs)
+- Ignore log volume -- implement log rotation and retention policies
+
+\`\`\`
+// DO: Structured security log (PII redacted)
+logger.warn("auth.failed", {
+  userId: attempt.userId,
+  ip: request.ip,
+  reason: "invalid_password",
+  attemptCount: 3,
+})
+
+// DON'T: Leak credentials
+logger.warn("Login failed for user@example.com with password P@ssw0rd!")
+\`\`\`
+</skill>
+
+## Output Format
+
+Present findings in this structure:
+
+### CRITICAL -- Must fix immediately (active exploits, data exposure)
+### HIGH -- Should fix before next release (auth gaps, injection vectors)
+### MEDIUM -- Plan to fix (missing headers, weak defaults)
+### LOW -- Consider improving (best practice deviations)
+
+For each finding, include: file path, line range, issue description, and a concrete remediation with code example.
+
+## Rules
+
+- ALWAYS check for hardcoded secrets, API keys, and tokens in source code.
+- ALWAYS verify authentication and authorization on every endpoint/handler.
+- ALWAYS run dependency audit commands when bash access is available.
+- DO use bash to run security scanning tools and audit commands.
+- DO NOT access the web.
+- DO NOT modify source code -- this agent is audit-only (edit permission is denied).`,
+	permission: {
+		edit: "deny",
+		bash: "allow",
+		webfetch: "deny",
+	} as const,
+});

package/src/hooks/anti-slop.ts

@@ -8,6 +8,8 @@ import {
 	CODE_EXTENSIONS,
 	COMMENT_PATTERNS,
 	EXT_COMMENT_STYLE,
+	isExcludedHashLine,
+	MINIMUM_SLOP_INDICATORS,
 	SLOP_PATTERNS,
 } from "./slop-patterns";
 
@@ -36,8 +38,12 @@ export function scanForSlopComments(content: string, ext: string): readonly Slop
 
 	const lines = content.split("\n");
 	const findings: SlopFinding[] = [];
+	const matchedPatternSources = new Set<string>();
 
 	for (let i = 0; i < lines.length; i++) {
+		// Exclude shebangs and hex-color lines from # comment scanning
+		if (commentStyle === "#" && isExcludedHashLine(lines[i])) continue;
+
 		const match = commentRegex.exec(lines[i]);
 		if (!match?.[1]) continue;
 
@@ -45,6 +51,7 @@ export function scanForSlopComments(content: string, ext: string): readonly Slop
 
 		for (const pattern of SLOP_PATTERNS) {
 			if (pattern.test(commentText)) {
+				matchedPatternSources.add(pattern.source);
 				findings.push(
 					Object.freeze({
 						line: i + 1,
@@ -57,6 +64,11 @@ export function scanForSlopComments(content: string, ext: string): readonly Slop
 		}
 	}
 
+	// Only report when enough distinct patterns match to reduce false positives
+	if (matchedPatternSources.size < MINIMUM_SLOP_INDICATORS) {
+		return Object.freeze([]);
+	}
+
 	return Object.freeze(findings);
 }
 
@@ -65,6 +77,17 @@ const FILE_WRITING_TOOLS: ReadonlySet<string> = Object.freeze(
 	new Set(["write_file", "edit_file", "write", "edit", "create_file"]),
 );
 
+/** Debounce interval: skip re-scanning a file if it was scanned within this window (ms). */
+const SCAN_DEBOUNCE_MS = 5000;
+
+/** Module-level debounce map: filePath -> lastScanTimestamp. */
+const scanTimestamps: Map<string, number> = new Map();
+
+/** Clear the debounce map. Exported for test isolation. */
+export function clearScanTimestamps(): void {
+	scanTimestamps.clear();
+}
+
 /**
  * Creates a tool.execute.after handler that scans for slop comments.
  * Best-effort: never throws, never blocks the pipeline.
@@ -101,6 +124,21 @@ export function createAntiSlopHandler(options: {
 		if (!resolved.startsWith(`${cwd}/`) && resolved !== cwd) return;
 
 		if (!isCodeFile(resolved)) return;
+
+		// Debounce: skip if this file was scanned within the debounce window
+		const now = Date.now();
+		const lastScan = scanTimestamps.get(resolved);
+		if (lastScan !== undefined && now - lastScan < SCAN_DEBOUNCE_MS) return;
+
+		// Claim the slot before yielding the event loop to prevent TOCTOU races
+		scanTimestamps.set(resolved, now);
+		if (scanTimestamps.size > 10_000) {
+			const cutoff = now - SCAN_DEBOUNCE_MS;
+			for (const [path, ts] of scanTimestamps) {
+				if (ts < cutoff) scanTimestamps.delete(path);
+			}
+		}
+
 		const ext = extname(resolved).toLowerCase();
 
 		// Read the actual file content — output.output is the tool's result message, not file content
@@ -108,7 +146,8 @@ export function createAntiSlopHandler(options: {
 		try {
 			fileContent = await readFile(resolved, "utf-8");
 		} catch {
-			return; // file unreadable — best-effort, skip
+			scanTimestamps.delete(resolved); // clear slot so next attempt is not blocked
+			return;
 		}
 
 		const findings = scanForSlopComments(fileContent, ext);

package/src/hooks/slop-patterns.ts

@@ -41,15 +41,35 @@ export const EXT_COMMENT_STYLE: Readonly<Record<string, string>> = Object.freeze
 
 /** Regex to extract comment text from a line given its comment prefix.
  * Matches both full-line comments and inline trailing comments.
- * Negative lookbehind (?<!:) prevents matching :// in URLs. */
+ * Negative lookbehind (?<!:) prevents matching :// in URLs.
+ * Hash-line exclusions (shebangs, hex colors) are handled by isExcludedHashLine(). */
 export const COMMENT_PATTERNS: Readonly<Record<string, RegExp>> = Object.freeze({
 	"//": /(?<!:)\/\/\s*(.+)/,
 	"#": /#\s*(.+)/,
 });
 
+/** Returns true if a line should be excluded from `#`-style comment scanning. */
+export function isExcludedHashLine(line: string): boolean {
+	// Shebangs: lines starting with #!
+	if (line.trimStart().startsWith("#!")) return true;
+	// Hex colors: lines containing #RGB / #RRGGBB / #RRGGBBAA patterns
+	if (/#[0-9a-fA-F]{3,8}\b/.test(line)) return true;
+	return false;
+}
+
+/**
+ * Minimum number of distinct pattern matches required to trigger a slop warning.
+ * A single match in isolation is likely a false positive for broad patterns.
+ */
+export const MINIMUM_SLOP_INDICATORS = 2;
+
 /**
  * Patterns matching obvious/sycophantic AI comment text.
  * Tested against extracted comment body only (not raw code lines).
+ *
+ * Broad adjective patterns (robust, comprehensive, powerful) require a narrating
+ * context prefix ("this is", "our", "the", "it is") to reduce false positives
+ * from legitimate technical usage.
  */
 export const SLOP_PATTERNS: readonly RegExp[] = Object.freeze([
 	/^increment\s+.*\s+by\s+\d+$/i,
@@ -60,11 +80,11 @@ export const SLOP_PATTERNS: readonly RegExp[] = Object.freeze([
 	/^import\s+(?:the\s+)?(?:necessary|required|needed)/i,
 	/^define\s+(?:the\s+)?(?:interface|type|class|function)/i,
 	/\belegantly?\b/i,
-	/\brobust(?:ly|ness)?\b/i,
-	/\bcomprehensive(?:ly)?\b/i,
+	/(?:this|the|it|our)\s+(?:is\s+)?(?:a\s+)?\brobust(?:ly|ness)?\b/i,
+	/(?:this|the|it|our)\s+(?:is\s+)?(?:a\s+)?\bcomprehensive(?:ly)?\b/i,
 	/\bseamless(?:ly)?\b/i,
 	/\blever(?:age|aging)\b/i,
-	/\bpowerful\b/i,
+	/(?:this|the|it|our)\s+(?:is\s+)?(?:a\s+)?\bpowerful\b/i,
 	/\bsophisticated\b/i,
 	/\bstate[\s-]of[\s-]the[\s-]art\b/i,
 	/\bcutting[\s-]edge\b/i,

package/src/installer.ts

@@ -1,4 +1,4 @@
-import { access, copyFile, readdir, unlink } from "node:fs/promises";
+import { access, copyFile, open, readdir, unlink } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { copyIfMissing, ensureDir, isEnoentError } from "./utils/fs-helpers";
 import { getAssetsDir, getGlobalConfigDir } from "./utils/paths";
@@ -139,14 +139,41 @@ async function processSkills(sourceDir: string, targetDir: string): Promise<Inst
 	return { copied, skipped, errors };
 }
 
+/** Marker string present in installer-generated file frontmatter. */
+const INSTALLER_MARKER = "opencode-autopilot";
+
+/** Read the first 200 bytes of a file to check for the installer marker. */
+async function hasInstallerMarker(filePath: string): Promise<boolean> {
+	let fh: import("node:fs/promises").FileHandle | undefined;
+	try {
+		fh = await open(filePath, "r");
+		const buf = Buffer.alloc(200);
+		const { bytesRead } = await fh.read(buf, 0, 200, 0);
+		const head = buf.toString("utf-8", 0, bytesRead);
+		return head.includes(INSTALLER_MARKER);
+	} finally {
+		try {
+			await fh?.close();
+		} catch {
+			/* ignore close errors to avoid masking the primary exception */
+		}
+	}
+}
+
 async function cleanupDeprecatedAssets(
 	targetDir: string,
 ): Promise<{ readonly removed: readonly string[]; readonly errors: readonly string[] }> {
 	const removed: string[] = [];
 	const errors: string[] = [];
 	for (const asset of DEPRECATED_ASSETS) {
+		const filePath = join(targetDir, asset);
 		try {
-			await unlink(join(targetDir, asset));
+			// Only delete if the file contains the installer marker.
+			// User-created files (without the marker) are left untouched.
+			const isOurs = await hasInstallerMarker(filePath);
+			if (!isOurs) continue;
+
+			await unlink(filePath);
 			removed.push(asset);
 		} catch (error: unknown) {
 			if (!isEnoentError(error)) {

package/src/memory/capture.ts

@@ -104,7 +104,11 @@ export function createMemoryCaptureHandler(deps: MemoryCaptureDeps) {
 		readonly event: { readonly type: string; readonly [key: string]: unknown };
 	}): Promise<void> => {
 		const { event } = input;
-		const properties = (event.properties ?? {}) as Record<string, unknown>;
+		const rawProps = event.properties ?? {};
+		const properties: Record<string, unknown> =
+			rawProps !== null && typeof rawProps === "object" && !Array.isArray(rawProps)
+				? (rawProps as Record<string, unknown>)
+				: {};
 
 		// Skip noisy events early
 		if (!CAPTURE_EVENT_TYPES.has(event.type)) return;
@@ -144,15 +148,16 @@ export function createMemoryCaptureHandler(deps: MemoryCaptureDeps) {
 				currentSessionId = null;
 				currentProjectKey = null;
 
-				// Defer pruning to avoid blocking the event loop
+				// Defer pruning to avoid blocking the session.deleted handler.
+				// Best-effort: will not run if the process exits before this microtask drains.
 				if (projectKey) {
-					setTimeout(() => {
+					queueMicrotask(() => {
 						try {
 							pruneStaleObservations(projectKey, db);
 						} catch (err) {
 							console.warn("[opencode-autopilot] pruneStaleObservations failed:", err);
 						}
-					}, 0);
+					});
 				}
 				return;
 			}

package/src/memory/decay.ts

@@ -16,6 +16,7 @@ import {
 	MIN_RELEVANCE_THRESHOLD,
 	TYPE_WEIGHTS,
 } from "./constants";
+import { getMemoryDb } from "./database";
 import { deleteObservation, getObservationsByProject } from "./repository";
 import type { ObservationType } from "./types";
 
@@ -90,5 +91,15 @@ export function pruneStaleObservations(
 		}
 	}
 
+	// Optimize the FTS5 index after pruning to reclaim space and improve query speed
+	if (pruned > 0) {
+		try {
+			const resolvedDb = db ?? getMemoryDb();
+			resolvedDb.run("INSERT INTO observations_fts(observations_fts) VALUES('optimize')");
+		} catch {
+			// best-effort — FTS optimize failure is non-critical
+		}
+	}
+
 	return Object.freeze({ pruned });
 }

package/src/memory/retrieval.ts

@@ -13,8 +13,14 @@
 
 import type { Database } from "bun:sqlite";
 import { CHARS_PER_TOKEN, DEFAULT_INJECTION_BUDGET } from "./constants";
+import { getMemoryDb } from "./database";
 import { computeRelevanceScore } from "./decay";
-import { getAllPreferences, getObservationsByProject, getProjectByPath } from "./repository";
+import {
+	getAllPreferences,
+	getObservationsByProject,
+	getProjectByPath,
+	updateAccessCount,
+} from "./repository";
 import type { Observation, Preference } from "./types";
 
 /**
@@ -250,11 +256,34 @@ export function retrieveMemoryContext(
 	const scored = scoreAndRankObservations(observations, halfLifeDays);
 	const preferences = getAllPreferences(db);
 
-	return buildMemoryContext({
+	const context = buildMemoryContext({
 		projectName: project.name,
 		lastSessionDate: project.lastUpdated,
 		observations: scored,
 		preferences,
 		tokenBudget,
 	});
+
+	// Batch-update access counts in a single transaction to avoid N+1 writes.
+	// Only observations that could plausibly fit in context are updated.
+	// Best-effort: failures are swallowed to avoid blocking retrieval.
+	const maxInContext = MAX_PER_GROUP * SECTION_ORDER.length;
+	const idsToUpdate = scored
+		.slice(0, maxInContext)
+		.map((obs) => obs.id)
+		.filter((id): id is number => id !== undefined);
+	if (idsToUpdate.length > 0) {
+		try {
+			const resolvedDb = db ?? getMemoryDb();
+			resolvedDb.run("BEGIN");
+			for (const id of idsToUpdate) {
+				updateAccessCount(id, db);
+			}
+			resolvedDb.run("COMMIT");
+		} catch {
+			// best-effort — access count update is non-critical
+		}
+	}
+
+	return context;
 }

package/src/orchestrator/artifacts.ts

@@ -12,8 +12,13 @@ export async function ensurePhaseDir(artifactDir: string, phase: Phase): Promise
 	return dir;
 }
 
-export function getArtifactRef(phase: Phase, filename: string): string {
-	return `phases/${phase}/${filename}`;
+/**
+ * Returns the absolute path to a phase artifact.
+ * This is the canonical path used in both handler file-existence checks
+ * AND dispatch prompts, ensuring agents write to the location handlers verify.
+ */
+export function getArtifactRef(artifactDir: string, phase: Phase, filename: string): string {
+	return join(getPhaseDir(artifactDir, phase), filename);
 }
 
 export const PHASE_ARTIFACTS: Readonly<Record<string, readonly string[]>> = Object.freeze({

package/src/orchestrator/confidence.ts

@@ -36,8 +36,9 @@ export function summarizeConfidence(entries: readonly ConfidenceEntry[]): {
 
 	const total = entries.length;
 
-	// Tie-break: prefer higher confidence (HIGH > MEDIUM > LOW)
-	let dominant: ConfidenceLevel = "MEDIUM"; // default for empty
+	// Default: no evidence of low confidence → assume HIGH (single-proposal fast path).
+	// This prevents empty ledgers from triggering expensive multi-proposal arena (depth=2).
+	let dominant: ConfidenceLevel = "HIGH";
 	if (total > 0) {
 		let maxCount = 0;
 		for (const level of LEVEL_PRIORITY) {