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

package/index.ts

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

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@prjct.app/pi-signals",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "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",
+    "bin"
+  ],
+  "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",
+    "pretest": "npm run build"
+  },
+  "bin": {
+    "pi-signals": "bin/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(new URL('../bin/cli.mjs', 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/host.ts

@@ -0,0 +1,15 @@
+import { mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { getPackageDir, VERSION } from '@earendil-works/pi-coding-agent';
+import { stateDir } from './config.ts';
+
+/** Record only the host's public SDK location, never credentials or model data. */
+export function rememberHost() {
+  const root = stateDir(), file = join(root, 'host.json');
+  const value = JSON.stringify({ packageDir: getPackageDir(), version: VERSION }) + '\n';
+  try { if (readFileSync(file, 'utf8') === value) return; } catch { /* First load. */ }
+  mkdirSync(root, { recursive: true, mode: 0o700 });
+  const temporary = join(root, `host-${randomUUID()}.tmp`);
+  writeFileSync(temporary, value, { mode: 0o600 }); renameSync(temporary, file);
+}

package/src/index.ts

@@ -0,0 +1,70 @@
+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';
+import { rememberHost } from './host.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 };
+  pi.on('session_start', () => { try { rememberHost(); } catch { /* A host path hint must not interrupt an active session. */ } });
+  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,86 @@
+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.');
+  if (await must(path, ['git', 'rev-parse', 'HEAD'], signal) !== base) return blocked('The agent changed the candidate base before verification; no precommitted changes are accepted.');
+  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>;