@prjct.app/pi-signals 0.0.0-stage → 0.1.0

package/index.ts

@@ -0,0 +1 @@
+export { default, installSignals, type SignalsDependencies } from './src/index.ts';

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "@prjct.app/pi-signals",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Local failure signals, daily agent-owned triage and verified repair candidates for Pi.",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "signals",
+    "triage",
+    "quality"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "dist"
+  ],
+  "dependencies": {
+    "@prjct.app/pi-secrets": "^0.2.6"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=1.0.4",
+    "@earendil-works/pi-coding-agent": ">=1.0.4",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "1.0.4",
+    "@earendil-works/pi-coding-agent": "1.0.4",
+    "@types/node": "^22.19.0",
+    "esbuild": "^0.28.2",
+    "tsx": "^4.20.0",
+    "typebox": "1.3.7",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "node --import ./tests/isolate.mjs --import tsx --test --test-concurrency=2 tests/*.test.ts",
+    "check:package": "npm pack --dry-run --ignore-scripts",
+    "build": "node scripts/build.mjs",
+    "prepack": "npm run build"
+  },
+  "bin": {
+    "pi-signals": "dist/cli.mjs"
+  }
+}

package/src/agent.ts

@@ -0,0 +1,50 @@
+import { join } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { createAgentSession, DefaultPackageManager, DefaultResourceLoader, getAgentDir, ModelRuntime, SessionManager, SettingsManager, type ToolDefinition } from '@earendil-works/pi-coding-agent';
+import { protectOutboundData } from '@prjct.app/pi-secrets/privacy';
+import { config, stateDir } from './config.ts';
+import type { SignalModel } from './schema.ts';
+
+export type AgentTask = { cwd: string; model?: SignalModel; prompt: string; tools: ToolDefinition[]; writable: boolean; signal?: AbortSignal };
+export type AgentRunner = (task: AgentTask) => Promise<void>;
+export const runAgent: AgentRunner = async task => {
+  const home = getAgentDir();
+  const configured = SettingsManager.create(task.cwd, home, { projectTrusted: false });
+  if (configured.drainErrors().length) throw new Error('Cannot read Pi settings for the signals worker.');
+  const effective = configured.getSettings();
+  const selected = task.model ?? (effective.defaultProvider && effective.defaultModel ? { provider: effective.defaultProvider, id: effective.defaultModel, thinkingLevel: effective.defaultThinkingLevel } : undefined);
+  if (!selected) throw new Error('No originating or configured Pi model is available. Select a model in Pi.');
+  const runtime = await ModelRuntime.create({ authPath: join(home, 'auth.json'), modelsPath: join(home, 'models.json'), allowModelNetwork: false });
+  const model = runtime.getModel(selected.provider, selected.id);
+  const manager = new DefaultPackageManager({ cwd: task.cwd, agentDir: home, settingsManager: configured });
+  const admitted = config().workerPackages;
+  const paths = manager.listConfiguredPackages().flatMap(pkg => {
+    if (!pkg.installedPath) return [];
+    const manifest = JSON.parse(readFileSync(join(pkg.installedPath, 'package.json'), 'utf8'));
+    return admitted.includes(manifest.name) ? (manifest.pi?.extensions ?? []).map((entry: string) => join(pkg.installedPath!, entry)) : [];
+  });
+  const settings = SettingsManager.inMemory({ ...effective, packages: [], extensions: [], cacheWarming: 'off' });
+  const loader = new DefaultResourceLoader({ cwd: task.cwd, agentDir: home, settingsManager: settings,
+    noExtensions: true, noSkills: true, noPromptTemplates: true, noThemes: true, additionalExtensionPaths: paths });
+  await loader.reload();
+  if (loader.getExtensions().errors.length) throw new Error('The worker could not load the admitted Pi extensions.');
+  const { session } = await createAgentSession({ cwd: task.cwd, agentDir: home, settingsManager: settings, resourceLoader: loader,
+    modelRuntime: runtime, model, thinkingLevel: selected.thinkingLevel, sessionManager: SessionManager.create(task.cwd, join(stateDir(), 'sessions')),
+    tools: ['read', 'grep', 'find', 'ls', 'bash', ...(task.writable ? ['edit', 'write'] : []), 'context_status', 'context_history', 'context_compact', ...task.tools.map(tool => tool.name)], customTools: task.tools });
+  const abort = () => { void session.abort(); };
+  task.signal?.addEventListener('abort', abort, { once: true });
+  try {
+    task.signal?.throwIfAborted();
+    await session.bindExtensions({ mode: 'rpc' });
+    const resolved = runtime.getModel(selected.provider, selected.id);
+    if (!resolved) throw new Error(`The originating model ${selected.provider}/${selected.id} is unavailable; no substitute was selected.`);
+    await session.setModel(resolved);
+    if (selected.thinkingLevel) session.setThinkingLevel(selected.thinkingLevel);
+    await session.prompt(await protectOutboundData(task.prompt));
+    task.signal?.throwIfAborted();
+  } finally {
+    task.signal?.removeEventListener('abort', abort);
+    await session.extensionRunner?.emit({ type: 'session_shutdown', reason: 'quit' });
+    session.dispose();
+  }
+};

package/src/cli.ts

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { fileURLToPath } from 'node:url';
+import { databasePath, config } from './config.ts';
+import { SignalStore } from './store.ts';
+
+async function main() {
+  const [action = 'status', argument] = process.argv.slice(2);
+  if (action === 'schedule' && argument === 'install') {
+    return (await import('./scheduler.ts')).installSchedule(fileURLToPath(import.meta.url));
+  }
+  if (action === 'once') {
+    const controller = new AbortController();
+    const abort = () => controller.abort(new Error('Signals worker cancelled'));
+    process.once('SIGTERM', abort); process.once('SIGINT', abort);
+    try { return await (await import('./worker.ts')).runDaily(argument === '--scheduled', controller.signal); }
+    finally { process.removeListener('SIGTERM', abort); process.removeListener('SIGINT', abort); }
+  }
+  const store = new SignalStore(databasePath());
+  try {
+    if (action === 'status') { const issues = store.list(); return { config: config(), issues: issues.slice(0, 20), nextOffset: issues.length > 20 ? 20 : null }; }
+    if (action === 'retry' && argument && /^[a-f0-9]{64}$/.test(argument)) return { queued: store.retry(argument) };
+    if (action === 'show' && argument) return { issue: store.get(argument), observations: store.observations(argument), runs: store.runs(argument) };
+    throw new Error('Usage: pi-signals status | show <id> | retry <id> | once [--scheduled] | schedule install');
+  } finally { store.close(); }
+}
+try { console.log(JSON.stringify(await main(), null, 2)); }
+catch (error) {
+  const { protectOutboundData } = await import('@prjct.app/pi-secrets/privacy');
+  console.error(await protectOutboundData(String(error)).catch(() => 'Signals failed; outbound privacy protection was unavailable.'));
+  process.exitCode = 1;
+}

package/src/commands.ts

@@ -0,0 +1,16 @@
+import { createLocalBashOperations } from '@earendil-works/pi-coding-agent';
+
+export type Check = { command: string; code: number; output: string; durationMs: number };
+export const quote = (value: string) => `'${value.replaceAll("'", "'\\''")}'`;
+/** Use Pi's public execution/cancellation backend, including process-tree cleanup. */
+export async function command(cwd: string, value: string | string[], signal?: AbortSignal): Promise<Check> {
+  const text = Array.isArray(value) ? value.map(quote).join(' ') : value;
+  const chunks: Buffer[] = [], start = performance.now();
+  const result = await createLocalBashOperations().exec(text, cwd, { onData: data => chunks.push(data), signal, timeout: 600 });
+  return { command: text, code: result.exitCode ?? 128, output: Buffer.concat(chunks).toString('utf8'), durationMs: performance.now() - start };
+}
+export async function must(cwd: string, value: string | string[], signal?: AbortSignal) {
+  const result = await command(cwd, value, signal);
+  if (result.code !== 0) throw new Error(`Command failed (${result.code}): ${result.command}\n${result.output}`);
+  return result.output.trim();
+}

package/src/config.ts

@@ -0,0 +1,48 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+import { DefaultPackageManager, getAgentDir, getPackageDir, SettingsManager, type ExtensionAPI, type ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type { Target } from './schema.ts';
+
+export const stateDir = () => join(process.env.PRJCT_HOME ?? join(homedir(), '.prjct'), 'shared', 'signals');
+export const databasePath = () => join(stateDir(), 'signals.sqlite');
+export type Repository = { path: string; base: string; setup: string[]; tests: string[] };
+export type Config = { enabled: boolean; packages: string[]; workerPackages: string[]; repositories: Record<string, Repository>; timezone: string; hour: number; minute: number; repair: boolean; delivery: 'local' };
+export function config(): Config {
+  const defaults: Config = { enabled: true, packages: ['@prjct.app/'], workerPackages: ['@prjct.app/pi-secrets', '@prjct.app/pi-context-control', '@prjct.app/pi-self-compact'], repositories: {}, timezone: 'America/Cancun', hour: 9, minute: 0, repair: false, delivery: 'local' };
+  try {
+    const raw = JSON.parse(readFileSync(join(stateDir(), 'config.json'), 'utf8'));
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('Expected an object');
+    const value: Config = { ...defaults, ...raw };
+    if (typeof value.enabled !== 'boolean' || typeof value.repair !== 'boolean' || value.delivery !== 'local'
+      || !Array.isArray(value.packages) || !value.packages.every(prefix => typeof prefix === 'string' && prefix.length > 0)
+      || !Array.isArray(value.workerPackages) || !value.workerPackages.every(name => typeof name === 'string' && name.length > 0)
+      || !Number.isInteger(value.hour) || value.hour < 0 || value.hour > 23 || !Number.isInteger(value.minute) || value.minute < 0 || value.minute > 59
+      || !value.repositories || typeof value.repositories !== 'object' || Array.isArray(value.repositories)) throw new Error('Invalid configuration');
+    new Intl.DateTimeFormat('en', { timeZone: value.timezone });
+    for (const repo of Object.values(value.repositories)) {
+      if (!repo || !isAbsolute(repo.path) || !/^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(repo.base) || repo.base.includes('..')
+        || !Array.isArray(repo.setup) || !Array.isArray(repo.tests) || ![...repo.setup, ...repo.tests].every(command => typeof command === 'string' && command.trim())) throw new Error('Invalid repository binding');
+    }
+    return value;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return defaults;
+    throw new Error('Invalid global signals configuration; processing is disabled until repaired.');
+  }
+}
+function manifestTarget(root: string): Target | undefined {
+  try {
+    const value = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+    return typeof value.name === 'string' && typeof value.version === 'string' ? { id: value.name, version: value.version } : undefined;
+  } catch { return undefined; }
+}
+export function targets(pi: ExtensionAPI, ctx: ExtensionContext, policy: Config): Target[] {
+  const effective = pi.getSettings();
+  const settings = effective.packages?.length ? SettingsManager.inMemory(effective) : SettingsManager.create(ctx.cwd, getAgentDir(), { projectTrusted: false });
+  if (settings.drainErrors().some(error => error.scope === 'global')) throw new Error('Cannot read the global Pi package catalog.');
+  const manager = new DefaultPackageManager({ cwd: ctx.cwd, agentDir: getAgentDir(), settingsManager: settings });
+  const installed = manager.listConfiguredPackages().flatMap(pkg => pkg.installedPath ? [manifestTarget(pkg.installedPath)].filter((value): value is Target => !!value) : [])
+    .filter(target => policy.packages.some(prefix => target.id === prefix || (prefix.endsWith('/') && target.id.startsWith(prefix))));
+  const core = manifestTarget(getPackageDir());
+  return [...new Map([...installed, ...(core ? [{ ...core, id: 'pi' }] : [])].map(target => [target.id, target])).values()];
+}

package/src/evidence.ts

@@ -0,0 +1,25 @@
+import { Type } from 'typebox';
+import type { ToolDefinition } from '@earendil-works/pi-coding-agent';
+import { protectOutboundData } from '@prjct.app/pi-secrets/privacy';
+
+export type EvidenceSource = readonly unknown[] | ((offset: number, limit: number) => unknown[]);
+/** Keep full observations in storage; the deciding agent chooses which pages to read. */
+export function evidenceTool(source: EvidenceSource) {
+  const seen: string[] = [];
+  const tool: ToolDefinition = {
+    name: 'signal_evidence', label: 'Read original signal evidence',
+    description: 'Read original issue observations by page. Nothing is discarded; follow nextOffset to inspect all sightings. Select a smaller limit for large reports.',
+    parameters: Type.Object({ offset: Type.Optional(Type.Integer({ minimum: 0 })), limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 20 })) }),
+    async execute(_id, raw) {
+      const input = raw as { offset?: number; limit?: number }, offset = input.offset ?? 0, limit = input.limit ?? 1;
+      const rows = typeof source === 'function' ? source(offset, limit + 1) : source.slice(offset, offset + limit + 1);
+      const items = await protectOutboundData(rows.slice(0, limit));
+      for (const item of items) {
+        const payload = (item as { payload?: { body?: string } }).payload;
+        seen.push(payload?.body ?? JSON.stringify(item));
+      }
+      return { content: [{ type: 'text', text: JSON.stringify({ items, nextOffset: rows.length > limit ? offset + limit : null }) }], details: {} };
+    },
+  };
+  return { tool, contains: (quote: string) => seen.some(text => text.includes(quote)) };
+}

package/src/index.ts

@@ -0,0 +1,68 @@
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { protectOutboundData } from '@prjct.app/pi-secrets/privacy';
+import { config, targets, databasePath } from './config.ts';
+import { hideLocalPaths, prepareReport } from './report.ts';
+import { InspectSchema, OBSERVATION, ReportSchema } from './schema.ts';
+import { SignalStore } from './store.ts';
+
+const defaults = { config, targets, protect: protectOutboundData, databasePath };
+export type SignalsDependencies = Partial<typeof defaults>;
+const result = (value: unknown) => ({ content: [{ type: 'text' as const, text: JSON.stringify(value) }], details: {} });
+const page = <T>(rows: T[], offset: number) => ({ items: rows.slice(0, 20), nextOffset: rows.length > 20 ? offset + 20 : null });
+export function installSignals(pi: ExtensionAPI, dependencies: SignalsDependencies = {}) {
+  const deps = { ...defaults, ...dependencies };
+  const catalog = (ctx: ExtensionContext) => {
+    const settings = deps.config();
+    if (!settings.enabled) throw new Error('Signals is disabled by global configuration.');
+    return deps.targets(pi, ctx, settings);
+  };
+  pi.registerTool({
+    name: 'signal_report', label: 'Record failure signal',
+    description: 'Record a local issue in the global .prjct database for an installed extension or Pi: latency regression, crash, or concrete response-quality regression. Supply a stable defect signature, exact session evidence, reproduction steps, expected and actual behavior. No GitHub or model request occurs during capture.',
+    promptGuidelines: ['When you detect a latency regression, crash, or concrete response-quality regression in Pi or an installed extension, record minimal evidence with signal_report, then continue the original task. Use signal_inspect for targets. Detection is a signal, not proof of causality; the active agent and later triage decide.'],
+    parameters: ReportSchema,
+    async execute(_id, input, _signal, _update, ctx) {
+      const target = catalog(ctx).find(target => target.id === input.target);
+      if (!target) throw new Error('Unknown component. Inspect targets before recording a signal.');
+      const capture = prepareReport(input, target, ctx);
+      const payload = await deps.protect(hideLocalPaths(capture.payload, ctx.cwd));
+      const store = new SignalStore(deps.databasePath());
+      try { return result(store.capture({ ...capture, payload })); } finally { store.close(); }
+    },
+  });
+  pi.registerTool({
+    name: 'signal_inspect', label: 'Inspect failure signals',
+    description: 'Read targets, local issues, or observations. For stored issue observations supply issueId; otherwise observations are native failures on this session branch. Paginated; no external calls.',
+    parameters: InspectSchema,
+    async execute(_id, input, _signal, _update, ctx) {
+      const allowed = catalog(ctx), offset = input.offset ?? 0;
+      if (input.action === 'targets') return result(page(allowed.slice(offset, offset + 21), offset));
+      if (input.action === 'observations' && !input.issueId) {
+        const entries = ctx.sessionManager.getBranch().filter(entry => entry.type === 'custom' && entry.customType === OBSERVATION).reverse();
+        return result(page(entries.slice(offset, offset + 21).map(entry => ({ entryId: entry.id, data: entry.type === 'custom' ? entry.data : undefined })), offset));
+      }
+      const store = new SignalStore(deps.databasePath());
+      try { return result(page<unknown>(input.action === 'issues' ? store.list(offset) : store.observations(input.issueId!, offset), offset)); }
+      finally { store.close(); }
+    },
+  });
+  pi.registerCommand('signals', {
+    description: 'Show local issues and daily triage configuration',
+    async handler(_args, ctx) {
+      try {
+        const settings = deps.config(), store = new SignalStore(deps.databasePath());
+        try { ctx.ui.notify(JSON.stringify({ enabled: settings.enabled, daily: `${settings.hour}:${String(settings.minute).padStart(2, '0')} ${settings.timezone}`, issues: page(store.list(), 0) }), 'info'); }
+        finally { store.close(); }
+      } catch { ctx.ui.notify('Cannot read signals configuration or database.', 'error'); }
+    },
+  });
+  pi.on('session_compact_failed', async (event, ctx) => {
+    if (event.aborted) return;
+    try {
+      if (!deps.config().enabled) return;
+      pi.appendEntry(OBSERVATION, await deps.protect(hideLocalPaths({ reason: event.reason, error: event.errorMessage ?? 'Compaction failed',
+        fromExtension: event.fromExtension, willRetry: event.willRetry, time: Date.now() }, ctx.cwd)));
+    } catch { /* A failed observer never interrupts recovery or stores unprotected evidence. */ }
+  });
+}
+export default installSignals;

package/src/repair.ts

@@ -0,0 +1,85 @@
+import { Type, type Static } from 'typebox';
+import { copyFile, lstat, mkdir } from 'node:fs/promises';
+import { dirname, join, resolve, sep } from 'node:path';
+import { protectOutboundData } from '@prjct.app/pi-secrets/privacy';
+import { runAgent, type AgentRunner } from './agent.ts';
+import { command, must, type Check } from './commands.ts';
+import { stateDir, type Repository } from './config.ts';
+import type { LocalIssue } from './store.ts';
+import { evidenceTool, type EvidenceSource } from './evidence.ts';
+
+const FixSchema = Type.Object({
+  explanation: Type.String({ minLength: 1 }),
+  testFiles: Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }),
+  regressionCommand: Type.String({ minLength: 1 }),
+  failurePattern: Type.String({ minLength: 8 }),
+}, { additionalProperties: false });
+type Fix = Static<typeof FixSchema>;
+const ReviewSchema = Type.Object({ fixesSignal: Type.Boolean(), testsMeaningful: Type.Boolean(), explanation: Type.String({ minLength: 1 }) });
+export type RepairResult = { status: 'verified' | 'blocked'; explanation: string; base: string; head?: string; branch?: string; path: string; checks: Check[]; review?: unknown };
+
+/** A regression test is replayed unchanged on the base and candidate, then the trusted suite runs. */
+export async function repair(issue: LocalIssue, repo: Repository, path: string, base: string, observations: EvidenceSource, signal?: AbortSignal, agent: AgentRunner = runAgent): Promise<RepairResult> {
+  const state: { fix?: Fix; review?: Static<typeof ReviewSchema> } = {};
+  const checks: Check[] = [];
+  const blocked = (explanation: string): RepairResult => ({ status: 'blocked', explanation, base, path, checks });
+  await agent({ cwd: path, model: issue.model, writable: true, signal,
+    prompt: `Repair signal ${issue.id} in this isolated worktree. Preserve the task, public Pi SDK architecture and model autonomy. No JEV, classifier substitution, hidden context pruning, or cost-based model changes. Keep the fix small and reuse existing code. Do not publish, push, merge, or commit; the coordinator owns release gates.\n`
+      + `Add a meaningful regression test reproducing the exact observed failure. The SAME new test files will be copied to unchanged base ${base} and must fail there with the specific failurePattern; on your fix they must pass repeatedly. Do not edit existing tests or weaken assertions merely to make the suite pass. For latency use comparable repeated measurements; for response quality use the original task constraints and a controlled expected response, not general intelligence claims.\n`
+      + `Read the original observations with signal_evidence. Use signal_fix to describe the fix and name only new test files (under tests/test/__tests__ or *.test.*/*.spec.*). Full suites: ${JSON.stringify(repo.tests)}.\n${JSON.stringify({ issue })}`,
+    tools: [evidenceTool(observations).tool, { name: 'signal_fix', label: 'Submit repair candidate', description: 'Submit the candidate for independent baseline, regression, suite and semantic checks. This does not mark it fixed.', parameters: FixSchema,
+      async execute(_id, input) { state.fix = input as Fix; return { content: [{ type: 'text', text: 'Candidate recorded for verification.' }], details: {} }; } }],
+  });
+  if (!state.fix) return blocked('No structured repair candidate was provided.');
+  if (!repo.tests.length) return blocked('No trusted package validation commands are configured.');
+  const fix = state.fix;
+  const baselinePath = join(stateDir(), 'worktrees', `baseline-${issue.id.slice(0, 12)}-${Date.now()}`);
+  await must(repo.path, ['git', 'worktree', 'add', '--detach', baselinePath, base], signal);
+  for (const setup of repo.setup) await must(baselinePath, setup, signal);
+  for (const file of fix.testFiles) {
+    if (file.startsWith('/') || file.split(/[\\/]/).some(part => part === '..' || part === '.git') || !/(^|\/)(__tests__|tests?)\/|\.(test|spec)\./.test(file)) return blocked('Regression files must be new tests within the worktree.');
+    const source = resolve(path, file), destination = resolve(baselinePath, file);
+    if (!source.startsWith(path + sep) || !destination.startsWith(baselinePath + sep)) return blocked('Regression file escaped the worktree.');
+    // Refuse symlinks throughout either path; do not copy arbitrary external files.
+    for (const root of [path, baselinePath]) {
+      let current = root;
+      for (const part of file.split('/')) {
+        current = join(current, part);
+        const stat = await lstat(current).catch(() => undefined);
+        if (stat?.isSymbolicLink()) return blocked('Regression paths must not contain symlinks.');
+      }
+    }
+    if ((await command(path, ['git', 'cat-file', '-e', `${base}:${file}`], signal)).code === 0) return blocked('Use a new regression test file so baseline assertions cannot be silently rewritten.');
+    await mkdir(dirname(destination), { recursive: true }); await copyFile(source, destination);
+  }
+  const files = [...new Set((await must(path, ['git', 'diff', '--name-only', '-z'], signal) + '\0' + await must(path, ['git', 'ls-files', '--others', '--exclude-standard', '-z'], signal)).split('\0').filter(Boolean))];
+  if (!files.length) return blocked('No changed files in the repair candidate.');
+  const branch = `signals/${issue.id.slice(0, 12)}-${Date.now()}`;
+  await must(path, ['git', 'switch', '-c', branch], signal);
+  await must(path, ['git', 'add', '--', ...files], signal);
+  const diff = await must(path, ['git', 'diff', '--cached', '--binary'], signal);
+  if (await protectOutboundData(diff) !== diff) return blocked('The candidate diff contains data caught by outbound protection; publication is blocked.');
+  await must(path, ['git', 'commit', '-m', `fix: ${issue.title}`], signal);
+  const head = await must(path, ['git', 'rev-parse', 'HEAD'], signal);
+  for (let sample = 0; sample < 3; sample++) {
+    const before = await command(baselinePath, fix.regressionCommand, signal); checks.push(before);
+    if (before.code === 0 || !before.output.includes(fix.failurePattern)) return blocked('The unchanged baseline did not consistently reproduce the claimed failure.');
+    const after = await command(path, fix.regressionCommand, signal); checks.push(after);
+    if (after.code !== 0) return blocked('The regression test still fails or is intermittent on the candidate.');
+  }
+  for (const test of repo.tests) {
+    const check = await command(path, test, signal); checks.push(check);
+    if (check.code !== 0) return blocked('A required package validation failed.');
+  }
+  await agent({ cwd: path, model: issue.model, writable: false, signal,
+    prompt: `Review repair ${head} against base ${base} for signal ${issue.id}. You use the same model and reasoning as the originating agent. Inspect git diff ${base}..${head}, the new regression tests and these measured checks. Use signal_evidence for original observations and signal_validation for full check output by index. Passing tests alone is insufficient: decide whether the change addresses the actual reported failure, whether the assertion is meaningful, and whether latency/quality comparisons have controlled baselines. Reject weakened tests, output suppression, unrelated changes and context/model degradation. Do not modify files or publish. Record signal_review, or leave the candidate blocked.\n${JSON.stringify(await protectOutboundData({ issue, fix, checks: checks.map(({ command, code, durationMs }, index) => ({ index, command, code, durationMs })) }))}`,
+    tools: [evidenceTool(observations).tool, { name: 'signal_validation', label: 'Read validation output', description: 'Read the complete recorded output of one check by its index.', parameters: Type.Object({ index: Type.Integer({ minimum: 0 }) }),
+      async execute(_id, raw) { const check = checks[(raw as { index: number }).index]; if (!check) throw new Error('Unknown validation index.'); return { content: [{ type: 'text', text: JSON.stringify(await protectOutboundData(check)) }], details: {} }; } },
+    { name: 'signal_review', label: 'Review regression repair', description: 'Record the semantic review of the exact tested candidate.', parameters: ReviewSchema,
+      async execute(_id, input) { state.review = input as Static<typeof ReviewSchema>; return { content: [{ type: 'text', text: 'Review recorded.' }], details: {} }; } }],
+  });
+  if (!state.review?.fixesSignal || !state.review.testsMeaningful) return blocked(state.review?.explanation ?? 'No evidence-backed review approval.');
+  if (await must(path, ['git', 'rev-parse', 'HEAD'], signal) !== head || await must(path, ['git', 'status', '--porcelain'], signal)) return blocked('The candidate changed after verification.');
+  if (await must(repo.path, ['git', 'rev-parse', `${repo.base}^{commit}`], signal) !== base) return blocked('The base advanced; revalidation is required before merge.');
+  return { status: 'verified', explanation: state.review.explanation, base, head, branch, path, checks: await protectOutboundData(checks), review: await protectOutboundData(state.review) };
+}

package/src/report.ts

@@ -0,0 +1,50 @@
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import { contentText } from '@earendil-works/pi-ai';
+import { VERSION, type ExtensionContext, type SessionEntry } from '@earendil-works/pi-coding-agent';
+import { OBSERVATION, type Capture, type ReportInput, type Target } from './schema.ts';
+
+export const entryText = (entry: SessionEntry): string => {
+  if (entry.type === 'message' && 'content' in entry.message) return contentText(entry.message.content);
+  if (entry.type === 'custom_message') return contentText(entry.content);
+  if (entry.type === 'custom' && entry.customType === OBSERVATION) return JSON.stringify(entry.data);
+  return '';
+};
+
+export function prepareReport(input: ReportInput, target: Target, ctx: ExtensionContext): Capture {
+  if (!input.title.trim() || !input.signature.trim() || !input.expected.trim() || !input.actual.trim()
+    || !input.steps.length || input.steps.some(step => !step.trim()) || !input.evidence.length) throw new Error('Include a title, stable defect signature, reproduction steps, expected and actual results, and evidence.');
+  const branch = ctx.sessionManager.getBranch();
+  const evidence = input.evidence.map(item => {
+    const entry = branch.findLast(entry => (!item.entryId || entry.id === item.entryId) && entryText(entry).includes(item.quote));
+    if (!entry) throw new Error('Evidence must quote an original entry on this session branch. Inspect observations or use context_history to recover the exact text.');
+    const source = entry.type === 'message' ? entry.message.role : entry.type;
+    return { source, quote: item.quote, entryId: entry.id };
+  });
+  if (input.reproduced && !evidence.some(item => item.source === 'toolResult' || item.source === 'custom')) throw new Error('A reproduced defect needs tool or native SDK evidence; a claim in prose alone is not execution evidence.');
+  const signature = input.signature.trim().toLowerCase().replace(/\s+/g, ' ');
+  const hash = (value: unknown) => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+  const id = hash([target.id, signature]);
+  const observationId = hash([id, ctx.sessionManager.getSessionId(), evidence.map(item => item.entryId), evidence.map(item => item.quote)]);
+  const quote = (value: string) => value.split('\n').map(line => `> ${line}`).join('\n');
+  const body = [
+    `## Observed problem\n\n${input.actual}`,
+    `## Expected behavior\n\n${input.expected}`,
+    `## Reproduction\n\nStatus: ${input.reproduced ? 'reproduced by the reporting agent' : 'observed; reproduction not independently confirmed'}.\n\n${input.steps.map((step, i) => `${i + 1}. ${step}`).join('\n')}`,
+    `## Evidence\n\n${evidence.map(item => `Source: ${item.source}\n\n${quote(item.quote)}`).join('\n\n')}`,
+    `## Environment\n\n- Component: ${target.id}@${target.version}\n- Pi: ${VERSION}\n- Model: ${ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : 'unavailable'}\n- Reasoning: ${ctx.thinkingLevel ?? 'unspecified'}\n- Node: ${process.version}\n- Platform: ${process.platform}/${process.arch}\n- Category: ${input.category}`,
+    input.measurements ? `## Measurements\n\n${JSON.stringify(input.measurements)}` : '',
+    'Recorded by the active Pi agent from selected evidence. Triage must evaluate causality and reproducibility; this signal does not establish a general change in model intelligence.',
+  ].filter(Boolean).join('\n\n');
+  return { id, observationId, component: target.id, version: target.version, category: input.category, payload: { title: input.title.trim(), body },
+    model: ctx.model ? { provider: ctx.model.provider, id: ctx.model.id, thinkingLevel: ctx.thinkingLevel } : undefined };
+}
+
+/** Publication uses a minimal report, never a copied transcript or automatic file attachments. */
+export function hideLocalPaths<T>(value: T, cwd: string): T {
+  const serialized = JSON.stringify(value);
+  const paths = new Map([[homedir(), '<home>'], [cwd, '<workspace>']]);
+  const protectedText = [...paths].filter(([path]) => path.length > 1).sort(([a], [b]) => b.length - a.length)
+    .reduce((text, [path, label]) => text.replaceAll(JSON.stringify(path).slice(1, -1), label), serialized);
+  return JSON.parse(protectedText) as T;
+}

package/src/scheduler.ts

@@ -0,0 +1,35 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, isAbsolute } from 'node:path';
+import { getAgentDir } from '@earendil-works/pi-coding-agent';
+import { command, must } from './commands.ts';
+import { config, stateDir } from './config.ts';
+
+const label = 'app.prjct.pi-signals';
+const xml = (value: string) => value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;').replaceAll("'", '&apos;');
+export function launchAgent(entry: string) {
+  if (!isAbsolute(entry)) throw new Error('Scheduler requires the absolute installed CLI path.');
+  const settings = config();
+  const variables = { PATH: process.env.PATH ?? '/usr/local/bin:/usr/bin:/bin', PI_CODING_AGENT_DIR: getAgentDir(),
+    ...(process.env.PRJCT_HOME ? { PRJCT_HOME: process.env.PRJCT_HOME } : {}) };
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0"><dict>
+<key>Label</key><string>${label}</string>
+<key>ProgramArguments</key><array>${[process.execPath, entry, 'once', '--scheduled'].map(value => `<string>${xml(value)}</string>`).join('')}</array>
+<key>EnvironmentVariables</key><dict>${Object.entries(variables).map(([key, value]) => `<key>${key}</key><string>${xml(value)}</string>`).join('')}</dict>
+<key>RunAtLoad</key><true/>
+<key>StartCalendarInterval</key><dict><key>Minute</key><integer>${settings.minute}</integer></dict>
+<key>StandardOutPath</key><string>${xml(join(stateDir(), 'worker.log'))}</string>
+<key>StandardErrorPath</key><string>${xml(join(stateDir(), 'worker-error.log'))}</string>
+<key>ProcessType</key><string>Background</string>
+</dict></plist>\n`;
+}
+export async function installSchedule(entry: string) {
+  if (process.platform !== 'darwin') throw new Error('Use an OS scheduler to run pi-signals once --scheduled hourly on this platform.');
+  const directory = join(homedir(), 'Library', 'LaunchAgents'), file = join(directory, `${label}.plist`);
+  await mkdir(directory, { recursive: true }); await mkdir(stateDir(), { recursive: true, mode: 0o700 });
+  await writeFile(file, launchAgent(entry), { mode: 0o600 });
+  const domain = `gui/${process.getuid!()}`;
+  const loaded = await command(stateDir(), ['launchctl', 'print', `${domain}/${label}`]);
+  if (loaded.code !== 0) await must(stateDir(), ['launchctl', 'bootstrap', domain, file]);
+  return { installed: true, file, schedule: config().timezone, existingProcessesStopped: false };
+}

package/src/schema.ts

@@ -0,0 +1,31 @@
+import { Type, type Static } from 'typebox';
+
+const text = (maxLength: number) => Type.String({ minLength: 1, maxLength });
+export const ReportSchema = Type.Object({
+  target: text(150),
+  title: text(160),
+  signature: text(240),
+  category: Type.Union([Type.Literal('latency'), Type.Literal('crash'), Type.Literal('response-quality')]),
+  steps: Type.Array(text(2000), { minItems: 1, maxItems: 20 }),
+  reproduced: Type.Boolean(),
+  expected: text(4000),
+  actual: text(4000),
+  evidence: Type.Array(Type.Object({ quote: Type.String({ minLength: 4, maxLength: 2000 }), entryId: Type.Optional(text(150)) }), { minItems: 1, maxItems: 8 }),
+  measurements: Type.Optional(Type.Object({ metric: text(150), unit: text(40), baseline: Type.Array(Type.Number({ minimum: 0 }), { minItems: 1, maxItems: 100 }), observed: Type.Array(Type.Number({ minimum: 0 }), { minItems: 1, maxItems: 100 }) })),
+}, { additionalProperties: false });
+export type ReportInput = Static<typeof ReportSchema>;
+export const InspectSchema = Type.Object({
+  action: Type.Union([Type.Literal('targets'), Type.Literal('issues'), Type.Literal('observations')]),
+  issueId: Type.Optional(text(64)),
+  offset: Type.Optional(Type.Integer({ minimum: 0 })),
+}, { additionalProperties: false });
+export type Target = { id: string; version: string };
+export type Payload = { title: string; body: string };
+export const OBSERVATION = 'signal-observation';
+export type SignalModel = { provider: string; id: string; thinkingLevel?: import('@earendil-works/pi-coding-agent').ExtensionContext['thinkingLevel'] };
+export type Capture = { id: string; observationId: string; component: string; version: string; category: ReportInput['category']; payload: Payload; model?: SignalModel };
+export const TriageSchema = Type.Object({
+  verdict: Type.Union([Type.Literal('attention'), Type.Literal('flaky'), Type.Literal('needs_evidence')]),
+  reason: text(6000), evidence: Type.Array(text(4000), { minItems: 1, maxItems: 20 }),
+}, { additionalProperties: false });
+export type Triage = Static<typeof TriageSchema>;

package/src/store.ts

@@ -0,0 +1,95 @@
+import { randomUUID } from 'node:crypto';
+import { chmodSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import type { Capture, Triage } from './schema.ts';
+
+export type Status = 'new' | 'triaging' | 'flaky' | 'needs_evidence' | 'attention' | 'repairing' | 'verified' | 'resolved' | 'blocked';
+export type LocalIssue = { id: string; component: string; category: string; title: string; status: Status; revision: number; sightings: number; created: number; updated: number; decision?: Triage; model?: Capture['model']; lastError?: string };
+export class SignalStore {
+  private readonly db: DatabaseSync;
+  constructor(path: string) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    this.db = new DatabaseSync(path); chmodSync(path, 0o600);
+    this.db.exec(`PRAGMA busy_timeout=3000; PRAGMA journal_mode=WAL;
+      CREATE TABLE IF NOT EXISTS issues (id TEXT PRIMARY KEY,component TEXT NOT NULL,category TEXT NOT NULL,title TEXT NOT NULL,status TEXT NOT NULL,
+        revision INTEGER NOT NULL,created INTEGER NOT NULL,updated INTEGER NOT NULL,model TEXT,decision TEXT,lastError TEXT);
+      CREATE TABLE IF NOT EXISTS observations (id TEXT PRIMARY KEY,issueId TEXT NOT NULL,version TEXT NOT NULL,payload TEXT NOT NULL,created INTEGER NOT NULL);
+      CREATE INDEX IF NOT EXISTS issue_observations ON observations(issueId,created);
+      CREATE TABLE IF NOT EXISTS runs (id TEXT PRIMARY KEY,issueId TEXT NOT NULL,revision INTEGER NOT NULL,phase TEXT NOT NULL,owner TEXT NOT NULL,
+        state TEXT NOT NULL,started INTEGER NOT NULL,finished INTEGER,result TEXT);
+      CREATE TABLE IF NOT EXISTS leases (name TEXT PRIMARY KEY,owner TEXT NOT NULL,expires INTEGER NOT NULL);
+      CREATE TABLE IF NOT EXISTS schedule (day TEXT PRIMARY KEY,started INTEGER NOT NULL,finished INTEGER)`);
+  }
+  close() { this.db.close(); }
+  private transaction<T>(work: () => T): T {
+    this.db.exec('BEGIN IMMEDIATE');
+    try { const result = work(); this.db.exec('COMMIT'); return result; }
+    catch (error) { this.db.exec('ROLLBACK'); throw error; }
+  }
+  get(id: string): LocalIssue | undefined {
+    const row = this.db.prepare('SELECT i.*,(SELECT COUNT(*) FROM observations o WHERE o.issueId=i.id) sightings FROM issues i WHERE id=?').get(id);
+    return row ? { ...row, decision: row.decision ? JSON.parse(String(row.decision)) : undefined, model: row.model ? JSON.parse(String(row.model)) : undefined } as unknown as LocalIssue : undefined;
+  }
+  list(offset = 0) { return this.db.prepare('SELECT id FROM issues ORDER BY updated DESC,id LIMIT 21 OFFSET ?').all(offset).map(row => this.get(String(row.id))!); }
+  observations(id: string, offset = 0, limit = 21) {
+    return this.db.prepare('SELECT * FROM observations WHERE issueId=? ORDER BY created,id LIMIT ? OFFSET ?').all(id, limit, offset)
+      .map(row => ({ ...row, payload: JSON.parse(String(row.payload)) }));
+  }
+  capture(value: Capture, now = Date.now()) {
+    return this.transaction(() => {
+      this.db.prepare("INSERT OR IGNORE INTO issues(id,component,category,title,status,revision,created,updated,model) VALUES(?,?,?,?,'new',0,?,?,?)")
+        .run(value.id, value.component, value.category, value.payload.title, now, now, value.model ? JSON.stringify(value.model) : null);
+      const added = this.db.prepare('INSERT OR IGNORE INTO observations(id,issueId,version,payload,created) VALUES(?,?,?,?,?)')
+        .run(value.observationId, value.id, value.version, JSON.stringify(value.payload), now).changes;
+      if (added) this.db.prepare("UPDATE issues SET revision=revision+1,updated=?,status=CASE WHEN status IN ('triaging','repairing') THEN status ELSE 'new' END WHERE id=?")
+        .run(now, value.id);
+      const issue = this.get(value.id)!;
+      return { id: issue.id, status: issue.status, sightings: issue.sightings, duplicate: !added };
+    });
+  }
+  pending() { return this.db.prepare("SELECT id FROM issues WHERE status IN ('new','attention') ORDER BY created,id").all().map(row => this.get(String(row.id))!); }
+  retry(id: string) { return !!this.db.prepare("UPDATE issues SET status='new',updated=? WHERE id=? AND status NOT IN ('triaging','repairing')").run(Date.now(), id).changes; }
+  acquire(name: string, durationMs: number, now = Date.now()): string | undefined {
+    const owner = randomUUID();
+    const changed = this.db.prepare('INSERT INTO leases(name,owner,expires) VALUES(?,?,?) ON CONFLICT(name) DO UPDATE SET owner=excluded.owner,expires=excluded.expires WHERE leases.expires<=?')
+      .run(name, owner, now + durationMs, now).changes;
+    return changed ? owner : undefined;
+  }
+  renew(name: string, owner: string, durationMs: number) {
+    return !!this.db.prepare('UPDATE leases SET expires=? WHERE name=? AND owner=? AND expires>?').run(Date.now() + durationMs, name, owner, Date.now()).changes;
+  }
+  release(name: string, owner: string) { this.db.prepare('DELETE FROM leases WHERE name=? AND owner=?').run(name, owner); }
+  private assertOwner(owner: string) {
+    if (!this.db.prepare("SELECT 1 FROM leases WHERE name='worker' AND owner=? AND expires>?").get(owner, Date.now())) throw new Error('Worker lease lost; stale decisions cannot be committed.');
+  }
+  due(day: string) { return !this.db.prepare('SELECT 1 FROM schedule WHERE day=? AND finished IS NOT NULL').get(day); }
+  startDay(day: string) { this.db.prepare('INSERT OR IGNORE INTO schedule(day,started) VALUES(?,?)').run(day, Date.now()); }
+  finishDay(day: string) { this.db.prepare('UPDATE schedule SET finished=? WHERE day=?').run(Date.now(), day); }
+  begin(issue: LocalIssue, owner: string, phase: 'triage' | 'repair') {
+    const id = randomUUID();
+    this.transaction(() => {
+      this.assertOwner(owner);
+      this.db.prepare('INSERT INTO runs(id,issueId,revision,phase,owner,state,started) VALUES(?,?,?,?,?,?,?)')
+        .run(id, issue.id, issue.revision, phase, owner, 'running', Date.now());
+      this.db.prepare('UPDATE issues SET status=?,lastError=NULL WHERE id=?').run(phase === 'triage' ? 'triaging' : 'repairing', issue.id);
+    });
+    return id;
+  }
+  finish(run: string, status: Status, result: unknown, decision?: Triage) {
+    this.transaction(() => {
+      const row = this.db.prepare('SELECT * FROM runs WHERE id=? AND state=?').get(run, 'running');
+      if (!row) throw new Error('The signals run is no longer active.');
+      this.assertOwner(String(row.owner));
+      this.db.prepare("UPDATE runs SET state='finished',finished=?,result=? WHERE id=?").run(Date.now(), JSON.stringify(result), run);
+      this.db.prepare("UPDATE issues SET status=CASE WHEN revision>? THEN 'new' ELSE ? END,decision=COALESCE(?,decision),updated=? WHERE id=?")
+        .run(Number(row.revision), status, decision ? JSON.stringify(decision) : null, Date.now(), String(row.issueId));
+    });
+  }
+  recover(owner: string) {
+    this.assertOwner(owner);
+    // An interrupted run never counts as fixed.
+    this.db.exec("UPDATE issues SET status='new',lastError='Previous worker interrupted; evidence retained' WHERE status IN ('triaging','repairing'); UPDATE runs SET state='interrupted' WHERE state='running'");
+  }
+  runs(id: string) { return this.db.prepare('SELECT * FROM runs WHERE issueId=? ORDER BY started').all(id).map(row => ({ ...row, id: String(row.id), state: String(row.state), result: row.result ? JSON.parse(String(row.result)) : undefined })); }
+}