@vigolium/piolium 0.0.1

package/agents/variant-scanner.md

@@ -0,0 +1,108 @@
+---
+name: variant-scanner
+tools: Glob, Grep, Read, Bash, Agent
+model: sonnet
+color: green
+permissionMode: bypassPermissions
+effort: low
+description: Phase 12 per-finding variant analysis agent that takes a confirmed vulnerability and searches for structural variants using the attack pattern registry's detection signatures, CodeQL on-demand queries, DFD/CFD slice analysis including Phase 10 Addendum discoveries, and chamber variant candidates
+---
+
+You are a variant hunter for Phase 12 of a security audit. You receive a single confirmed finding and search the entire codebase for structural variants — the same vulnerability pattern in different locations.
+
+## Inputs
+
+You receive:
+- **Finding path**: `archon/findings-draft/<phase>-<NNN>-<slug>.md`
+- **NNN range**: your assigned finding ID range for variant drafts
+- **KB path**: `archon/attack-surface/knowledge-base-report.md`
+
+## Context Loading
+
+1. Read the finding draft to understand the root cause and code pattern
+2. Read `archon/attack-pattern-registry.json` — find the matching pattern entry
+3. Read `## Phase 10 Addendum` in the KB — new attack surfaces discovered during chamber debates
+4. Check `archon/chamber-workspace/*/variant-candidates/` for pre-identified candidates
+5. Read `archon/codeql-artifacts/entry-points.json` and `sinks.json` for structurally similar
+   entry/sink combinations
+
+## Variant Search Strategy
+
+### 1. Registry-Driven Search
+If the attack pattern registry has a `detection_signature` for this pattern:
+- Run the CodeQL query against `archon/codeql-artifacts/db/`
+- Run the Semgrep rule against the codebase
+- Run the grep pattern across the codebase
+- Each match is a variant candidate
+
+### 2. AST-Level Structural Search
+Write and run a CodeQL query that searches for the same AST-level structure:
+```bash
+codeql query run \
+  --database=archon/codeql-artifacts/db/ \
+  --output=archon/tmp/variant.bqrs \
+  -- archon/codeql-queries/variant-<slug>.ql
+codeql bqrs decode --format=json archon/tmp/variant.bqrs
+```
+
+### 3. Flow Shape Search
+Look for the same flow shape (source type -> transformation pattern -> sink type) in:
+- Sibling components sharing the same framework
+- Alternate transports (HTTP, WebSocket, gRPC, CLI)
+- Background job consumers processing the same data
+
+### 4. Phase 10 Addendum Targets
+Read the `## Phase 10 Addendum` for newly discovered attack surfaces. Check if the confirmed
+finding's pattern appears on any of these new surfaces.
+
+### 5. Chamber Variant Candidates
+Check `archon/chamber-workspace/*/variant-candidates/` for pre-identified candidates
+matching this finding's root cause.
+
+## Variant Validation
+
+For each candidate variant:
+1. Confirm the same root cause is present (not just syntactic similarity)
+2. Confirm attacker-controlled input reaches the variant location
+3. Confirm no blocking protection exists that was absent in the original
+4. Assign severity (start at MEDIUM; upgrade to HIGH for remote + trust boundary + no preconditions; CRITICAL for RCE/auth bypass + unauthenticated + internet-facing)
+
+Only retain variants rated **Medium or higher**.
+
+## Output
+
+Write each confirmed variant to `archon/findings-draft/p12-<NNN>-<slug>.md` using this template:
+
+```
+Phase: 10
+Sequence: NNN
+Slug: <slug>
+Verdict: VALID
+Rationale: <one-sentence>
+Severity-Original: <MEDIUM|HIGH|CRITICAL>
+PoC-Status: pending
+Origin-Finding: <path to original finding>
+Origin-Pattern: <attack pattern registry ID>
+
+## Summary
+## Location
+## Attacker Control
+## Trust Boundary Crossed
+## Impact
+## Evidence
+## Reproduction Steps
+```
+
+Fields:
+- `Phase: 10`
+- `Verdict: VALID`
+- Reference the original finding as the pattern source
+- Include code path evidence
+
+Update `archon/attack-pattern-registry.json` — append each confirmed variant to
+the pattern's `confirmed_instances`.
+
+## Completion
+
+When all search strategies are exhausted, report to the orchestrator:
+"Variant analysis complete for <finding-slug>. Variants found: <count>."

package/agents/variant-spotter.md

@@ -0,0 +1,110 @@
+---
+name: variant-spotter
+tools: Glob, Grep, Read, Bash
+model: sonnet
+color: cyan
+permissionMode: bypassPermissions
+effort: low
+background: true
+description: Phase 10 Review Chamber concurrent variant hunter that monitors debate transcripts for confirmed vulnerability patterns and immediately searches for structural variants in sibling components, alternate transports, and adjacent enforcement paths, front-loading Phase 12 variant analysis while chamber context is hot
+---
+
+You are a concurrent variant hunter operating alongside a Review Chamber debate. While the chamber debates specific hypotheses, you search for the same vulnerability patterns elsewhere in the codebase. Your work front-loads Phase 12 variant analysis.
+
+## Your Chamber Assignment
+
+Read the chamber's `debate.md` to understand:
+- Which threat cluster the chamber is investigating
+- Confirmed findings (look for `Verdict: VALID` entries in Synthesis rounds)
+
+## Monitoring Protocol
+
+1. Read `archon/chamber-workspace/<chamber-id>/debate.md` after each round marker appears (`## Round N`). When a `Status: CLOSED` header is found, stop monitoring and report completion.
+2. When a hypothesis receives `Verdict: VALID`, extract:
+   - The root cause pattern (e.g., "ObjectInputStream.readObject() without filter")
+   - The affected code location
+   - The detection approach used by the Tracer
+3. Also read `archon/attack-pattern-registry.json` for patterns from other chambers
+
+## Variant Search Strategy
+
+For each confirmed pattern:
+
+### 1. Grep-Based Discovery
+Search the entire codebase for the same code pattern:
+```bash
+# Example: find all ObjectInputStream.readObject() calls
+grep -rn "ObjectInputStream.*readObject" --include="*.java" .
+```
+
+### 2. CodeQL Structural Search
+If a detection signature exists in the attack pattern registry, run it:
+```bash
+codeql query run \
+  --database=archon/codeql-artifacts/db/ \
+  --output=archon/tmp/variant-search.bqrs \
+  -- archon/codeql-queries/on-demand-variant-<slug>.ql
+codeql bqrs decode --format=json archon/tmp/variant-search.bqrs
+```
+
+### 3. Sibling Component Check
+If the confirmed finding is in component A, check components B, C, D that share the same:
+- Trust boundary
+- Data flow pattern
+- Framework usage
+- Dependency
+
+### 4. Alternate Transport Check
+If the confirmed finding is via HTTP, check the same logic via:
+- WebSocket
+- gRPC
+- GraphQL
+- CLI interface
+- Background job/queue consumer
+
+## Output
+
+Write each variant candidate to its own file:
+
+```
+archon/chamber-workspace/<chamber-id>/variant-candidates/<slug>.md
+```
+
+Format:
+
+```markdown
+# Variant Candidate: <title>
+
+Origin-Finding: <finding draft path of the original confirmed vulnerability>
+Origin-Pattern: <attack pattern registry ID if exists>
+
+## Location
+File: <path>
+Function: <name>
+Line: <number>
+
+## Similarity
+- Same root cause: <yes/no, explanation>
+- Same code pattern: <yes/no, grep evidence>
+- Same trust boundary: <yes/no>
+- Same attacker-reachable: <unknown — needs Tracer verification>
+
+## Quick Assessment
+<Brief assessment of whether this looks like a real variant or a false match.
+Note: this is a preliminary assessment, NOT a verdict. The Synthesizer or Phase 12
+will make the final determination.>
+```
+
+## Scope Rules
+
+- Search the ENTIRE codebase, not just the chamber's assigned DFD slices
+- Do NOT participate in the debate — you read transcripts but never write to debate.md
+- Do NOT issue verdicts on variants — write candidates for the Synthesizer to evaluate
+- Prioritize patterns confirmed at HIGH or CRITICAL severity
+- Skip patterns where the detection signature has already been run by SAST (Phase 4 coverage)
+
+## Handoff to Phase 12
+
+Variant candidates not processed by the Synthesizer before chamber closure are preserved in
+`archon/chamber-workspace/<chamber-id>/variant-candidates/` for Phase 12 variant analysis
+to consume as its starting target list.

package/bin/piolium.mjs

@@ -0,0 +1,376 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import {
+	chmodSync,
+	copyFileSync,
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	rmSync,
+	statSync,
+	writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const DEFAULT_PROVIDER = "openai-codex";
+const DEFAULT_MODEL = "gpt-5.5";
+const DEFAULT_THINKING_LEVEL = "high";
+const DEFAULT_THEME = "piolium-srcery";
+
+const PACKAGE_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+function main(argv) {
+	const paths = resolvePaths();
+	const [command, ...rest] = argv;
+
+	if (command === "--help" || command === "-h") {
+		printHelp();
+		return 0;
+	}
+	if (command === "doctor") {
+		bootstrapConfig(paths, { syncEmptyAuth: true });
+		return runDoctor(paths);
+	}
+	if (command === "auth") {
+		bootstrapConfig(paths);
+		return runAuthCommand(paths, rest);
+	}
+	if (command === "reset-auth") {
+		bootstrapConfig(paths, { createAuth: false });
+		return resetAuth(paths);
+	}
+	if (command === "login") {
+		bootstrapConfig(paths);
+		return runPi(["/login", ...rest], paths);
+	}
+
+	bootstrapConfig(paths, { syncEmptyAuth: true });
+	return runPi(command === "--" ? rest : argv, paths);
+}
+
+function resolvePaths() {
+	const homeDir = expandHome(process.env.PIOLIUM_HOME || join(homedir(), ".piolium"));
+	const packageDir = resolve(expandHome(process.env.PIOLIUM_PACKAGE_DIR || PACKAGE_DIR));
+	const agentDir = resolve(expandHome(process.env.PIOLIUM_AGENT_DIR || join(homeDir, "agent")));
+	const sessionDir = resolve(
+		expandHome(process.env.PIOLIUM_SESSION_DIR || join(agentDir, "session")),
+	);
+	const sourcePiAgentDir = resolve(
+		expandHome(process.env.PIOLIUM_SOURCE_PI_AGENT_DIR || join(homedir(), ".pi", "agent")),
+	);
+	return {
+		homeDir,
+		packageDir,
+		agentDir,
+		sessionDir,
+		settingsPath: join(agentDir, "settings.json"),
+		authPath: join(agentDir, "auth.json"),
+		sourcePiSettingsPath: join(sourcePiAgentDir, "settings.json"),
+		sourcePiAuthPath: join(sourcePiAgentDir, "auth.json"),
+	};
+}
+
+function expandHome(value) {
+	if (value === "~") return homedir();
+	if (value.startsWith("~/")) return join(homedir(), value.slice(2));
+	return value;
+}
+
+function bootstrapConfig(paths, options = {}) {
+	const { createAuth = true, syncEmptyAuth = false } = options;
+	mkdirSync(paths.agentDir, { recursive: true });
+	mkdirSync(paths.sessionDir, { recursive: true });
+	ensureSettings(paths);
+	if (createAuth) ensureEmptyAuth(paths);
+	if (syncEmptyAuth) syncEmptyAuthFromPi(paths);
+}
+
+function ensureSettings(paths) {
+	const current = readJsonObject(paths.settingsPath, { strict: true }) || {};
+	const source = readJsonObject(paths.sourcePiSettingsPath) || {};
+	const next = { ...current };
+	const packages = Array.isArray(next.packages) ? [...next.packages] : [];
+	if (
+		!packages.some((entry) =>
+			packageEntryMatches(entry, paths.packageDir, dirname(paths.settingsPath)),
+		)
+	) {
+		packages.unshift(paths.packageDir);
+		next.packages = packages;
+	}
+	for (const key of ["defaultProvider", "defaultModel", "defaultThinkingLevel", "theme"]) {
+		if (next[key] !== undefined) continue;
+		if (source[key] !== undefined) next[key] = source[key];
+	}
+	next.defaultProvider ??= DEFAULT_PROVIDER;
+	next.defaultModel ??= DEFAULT_MODEL;
+	next.defaultThinkingLevel ??= DEFAULT_THINKING_LEVEL;
+	next.theme ??= DEFAULT_THEME;
+	next.sessionDir ??= paths.sessionDir;
+	writeJsonObjectIfChanged(paths.settingsPath, current, next, 0o600);
+}
+
+function packageEntryMatches(entry, packageDir, baseDir) {
+	const value = typeof entry === "string" ? entry : entry?.source;
+	if (typeof value !== "string") return false;
+	const resolved = isAbsolute(expandHome(value))
+		? resolve(expandHome(value))
+		: resolve(baseDir, expandHome(value));
+	return resolved === packageDir;
+}
+
+function ensureEmptyAuth(paths) {
+	if (existsSync(paths.authPath)) return;
+	writeFileSync(paths.authPath, "{}\n", "utf8");
+	chmodIfPossible(paths.authPath, 0o600);
+}
+
+function syncEmptyAuthFromPi(paths) {
+	if (!isEmptyAuthFile(paths.authPath) || !existsSync(paths.sourcePiAuthPath)) return;
+	if (isEmptyAuthFile(paths.sourcePiAuthPath)) return;
+	console.warn(
+		`[piolium] warning: ${paths.authPath} is empty; syncing auth from ${paths.sourcePiAuthPath}.`,
+	);
+	copyAuthFile(paths.sourcePiAuthPath, paths.authPath, "Synced");
+}
+
+function runAuthCommand(paths, args) {
+	const [command, ...rest] = args;
+	if (command === "import") return importAuth(paths, rest);
+	if (command === "sync") return syncAuth(paths, rest);
+	if (command === "path") {
+		console.log(paths.authPath);
+		return 0;
+	}
+	console.error(
+		"Usage: piolium auth sync | piolium auth import [--force] [--from <auth.json>] | piolium auth path",
+	);
+	return 2;
+}
+
+function importAuth(paths, args) {
+	let sourcePath = paths.sourcePiAuthPath;
+	let force = false;
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === "--force") {
+			force = true;
+		} else if (arg === "--from" && args[i + 1]) {
+			sourcePath = resolve(expandHome(args[++i]));
+		} else if (arg?.startsWith("--from=")) {
+			sourcePath = resolve(expandHome(arg.slice("--from=".length)));
+		} else {
+			console.error(`Unknown auth import argument: ${arg}`);
+			return 2;
+		}
+	}
+	if (!existsSync(sourcePath)) {
+		console.error(`No source auth file found at ${sourcePath}`);
+		return 1;
+	}
+	const targetExists = existsSync(paths.authPath);
+	if (targetExists && !force && !isEmptyAuthFile(paths.authPath)) {
+		console.error(
+			`${paths.authPath} already contains credentials. Re-run with --force to replace it.`,
+		);
+		return 1;
+	}
+	mkdirSync(dirname(paths.authPath), { recursive: true });
+	copyFileSync(sourcePath, paths.authPath);
+	chmodIfPossible(paths.authPath, 0o600);
+	console.log(`Imported auth into ${paths.authPath}`);
+	return 0;
+}
+
+function syncAuth(paths, args) {
+	if (args.length > 0) {
+		console.error("Usage: piolium auth sync");
+		return 2;
+	}
+	return copyAuthFile(paths.sourcePiAuthPath, paths.authPath, "Synced");
+}
+
+function copyAuthFile(sourcePath, targetPath, verb) {
+	if (!existsSync(sourcePath)) {
+		console.error(`No source auth file found at ${sourcePath}`);
+		return 1;
+	}
+	if (resolve(sourcePath) === resolve(targetPath)) {
+		console.log(`Auth already points at ${targetPath}`);
+		return 0;
+	}
+	mkdirSync(dirname(targetPath), { recursive: true });
+	copyFileSync(sourcePath, targetPath);
+	chmodIfPossible(targetPath, 0o600);
+	console.log(`${verb} auth from ${sourcePath} into ${targetPath}`);
+	return 0;
+}
+
+function resetAuth(paths) {
+	if (existsSync(paths.authPath)) rmSync(paths.authPath, { force: true });
+	ensureEmptyAuth(paths);
+	console.log(`Reset auth at ${paths.authPath}`);
+	return 0;
+}
+
+function runDoctor(paths) {
+	const piPath = resolveCommand(process.env.PIOLIUM_PI_BIN || "pi");
+	const authState = authStatus(paths.authPath);
+	const settings = readJsonObject(paths.settingsPath);
+	const hasPackage =
+		!!settings &&
+		Array.isArray(settings.packages) &&
+		settings.packages.some((entry) =>
+			packageEntryMatches(entry, paths.packageDir, dirname(paths.settingsPath)),
+		);
+
+	console.log("Piolium standalone");
+	console.log(`  home:       ${paths.homeDir}`);
+	console.log(
+		`  package:    ${existsSync(paths.packageDir) ? "ok" : "missing"} ${paths.packageDir}`,
+	);
+	console.log(`  agent:      ${paths.agentDir}`);
+	console.log(`  sessions:   ${paths.sessionDir}`);
+	console.log(`  settings:   ${hasPackage ? "ok" : "missing package entry"} ${paths.settingsPath}`);
+	console.log(`  auth:       ${authState} ${paths.authPath}`);
+	console.log(`  pi:         ${piPath || "not found"}`);
+	if (!piPath) return 1;
+	return existsSync(paths.packageDir) && hasPackage ? 0 : 1;
+}
+
+function runPi(args, paths) {
+	const piCommand = process.env.PIOLIUM_PI_BIN || "pi";
+	const finalArgs = hasSessionDirArg(args) ? args : ["--session-dir", paths.sessionDir, ...args];
+	const consoleStream = defaultConsoleStreamEnv(finalArgs);
+	const result = spawnSync(piCommand, finalArgs, {
+		stdio: "inherit",
+		env: {
+			...process.env,
+			PI_CODING_AGENT_DIR: paths.agentDir,
+			...(consoleStream === undefined ? {} : { PIOLIUM_CONSOLE_STREAM: consoleStream }),
+		},
+	});
+	if (result.error) {
+		console.error(`Failed to run ${piCommand}: ${result.error.message}`);
+		return 1;
+	}
+	return result.status ?? 1;
+}
+
+function defaultConsoleStreamEnv(args) {
+	if (process.env.PIOLIUM_CONSOLE_STREAM !== undefined) return process.env.PIOLIUM_CONSOLE_STREAM;
+	return hasPioliumPrompt(args) ? "1" : undefined;
+}
+
+function hasPioliumPrompt(args) {
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if ((arg === "-p" || arg === "--prompt") && args[i + 1]?.includes("/piolium-")) return true;
+		if ((arg.startsWith("-p=") || arg.startsWith("--prompt=")) && arg.includes("/piolium-")) {
+			return true;
+		}
+	}
+	return false;
+}
+
+function hasSessionDirArg(args) {
+	return args.some((arg) => arg === "--session-dir" || arg.startsWith("--session-dir="));
+}
+
+function readJsonObject(path, options = {}) {
+	if (!existsSync(path)) return undefined;
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf8"));
+		return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : undefined;
+	} catch (error) {
+		if (options.strict) {
+			const message = error instanceof Error ? error.message : String(error);
+			throw new Error(`Invalid JSON in ${path}: ${message}`);
+		}
+		return undefined;
+	}
+}
+
+function writeJsonObjectIfChanged(path, before, after, mode) {
+	const beforeText = JSON.stringify(before, null, 2);
+	const afterText = `${JSON.stringify(after, null, 2)}\n`;
+	if (existsSync(path) && `${beforeText}\n` === afterText) return;
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, afterText, "utf8");
+	chmodIfPossible(path, mode);
+}
+
+function isEmptyAuthFile(path) {
+	try {
+		const text = readFileSync(path, "utf8").trim();
+		return text === "" || text === "{}";
+	} catch {
+		return true;
+	}
+}
+
+function authStatus(path) {
+	if (!existsSync(path)) return "missing";
+	if (isEmptyAuthFile(path)) return "empty";
+	try {
+		const size = statSync(path).size;
+		return size > 0 ? "configured" : "empty";
+	} catch {
+		return "unknown";
+	}
+}
+
+function chmodIfPossible(path, mode) {
+	try {
+		chmodSync(path, mode);
+	} catch {
+		// Best effort only. Some filesystems ignore POSIX modes.
+	}
+}
+
+function resolveCommand(command) {
+	if (command.includes("/") && existsSync(command)) return command;
+	const result = spawnSync("sh", ["-c", `command -v "$1"`, "sh", command], {
+		encoding: "utf8",
+	});
+	return result.status === 0 ? result.stdout.trim() : undefined;
+}
+
+function printHelp() {
+	console.log(`piolium - isolated Pi launcher for Piolium
+
+Usage:
+  piolium [pi args...]
+  piolium login
+  piolium doctor
+  piolium auth sync
+  piolium auth import [--force] [--from <auth.json>]
+  piolium auth path
+  piolium reset-auth
+
+Environment:
+  PIOLIUM_HOME                 Default: ~/.piolium
+  PIOLIUM_PACKAGE_DIR          Default: directory containing this package
+  PIOLIUM_AGENT_DIR            Default: ~/.piolium/agent
+  PIOLIUM_SESSION_DIR          Default: ~/.piolium/agent/session
+  PIOLIUM_SOURCE_PI_AGENT_DIR  Default: ~/.pi/agent
+  PIOLIUM_PI_BIN               Default: pi
+
+Examples:
+  piolium
+  piolium -p "/piolium-balanced --fresh"
+  piolium auth sync
+  piolium auth import
+`);
+}
+
+try {
+	const exitCode = main(process.argv.slice(2));
+	process.exit(exitCode);
+} catch (error) {
+	console.error(error instanceof Error ? error.message : String(error));
+	process.exit(1);
+}

package/extensions/piolium/_vendor/yaml.bundle.d.mts

@@ -0,0 +1,6 @@
+// Hand-written shim for the bundled `yaml` package (extensions/piolium/_vendor/yaml.bundle.mjs).
+// We only consume `parse` and `stringify`; everything else is intentionally
+// omitted to keep the surface minimal.
+
+export function parse(src: string, options?: unknown): unknown;
+export function stringify(value: unknown, options?: { lineWidth?: number; [k: string]: unknown }): string;