# Consigliere supervisor — corrected local release

This is a one-pass enterprise-management supervisor for macOS/Linux with Python 3.10+. It is not the entire Qzotic/Foresixa ecosystem, a daemon, mobile dashboard, trading engine, IRS transmitter or independent assurance certification. No simulated operational records, credentials or approved rules are generated.

## Install and test on your Mac

Stop previous supervisor jobs and other database writers before migration. Extract this archive. From its folder run:

```bash
bash install_mac.sh /Users/bpa/ForesixaQuant
cd /Users/bpa/ForesixaQuant
python3 run_all_tests.py
```

The installer runs isolated tests, backs up existing Python files and replaces the two files atomically, one at a time. It does not start the runtime or touch your operating database. This environment cannot write directly to your Mac. Do not use the older prototype installer for this release.

A normal one-pass run:

```bash
python3 consigliere_supervisor.py --root /Users/bpa/ForesixaQuant
```

That run can migrate the database and ingest signed input files. Actions and network sending are disabled unless their explicit flags are supplied:

```bash
python3 consigliere_supervisor.py --root /Users/bpa/ForesixaQuant --execute-actions --send-notifications
```

Use those flags only after the host-specific dependencies below are verified. No cron or launchd service is installed. Scheduling, availability, restart receipts and live end-to-end testing remain deployment work.

## Authentication contract

Create sender_keys.json on the host, owned by you with mode 600 or 400. It maps trusted sender IDs to newly generated 32–64 byte random keys encoded as lowercase hex. Do not reuse any key previously pasted in chat. Each configured sender currently has enterprise-wide management-update authority: only configure trusted management senders. Per-product sender authorization is outside this release; do not give customer/learner accounts these keys.

Incoming JSON:

```json
{
  "security_headers": {
    "sender_id": "manager",
    "event_uuid": "a-new-UUID-per-event",
    "issued_at": "timezone-aware-ISO-timestamp",
    "signature": "lowercase-HMAC-SHA256-hex"
  },
  "metadata": {
    "project_name": "your actual project",
    "vertical": "ACCOUNTING",
    "lifecycle_state": "ACTIVE",
    "deadline": "timezone-aware-ISO-timestamp",
    "budget_value": "100.00"
  }
}
```

Sign exactly canonical(payload): remove security_headers.signature; serialize using Python json.dumps(sort_keys=True, separators=(',', ':'), ensure_ascii=False, allow_nan=False); UTF-8 encode; HMAC-SHA256 using the sender key. Producers in other languages must reproduce these bytes; do not assume a different JSON canonicalization matches. The previous transmission_token_hash protocol is intentionally rejected. Reject duplicate JSON keys. New events expire after 24 hours and older/equal timestamps cannot overwrite a newer accepted project update. Exact journaled replays archive without executing again; reused IDs with different content quarantine. Preserve producer keys securely and rotate/revoke them through the private configuration.

Processed and rejected input files are retained in private processed/quarantine folders. Retention/archival disposal policies and encryption-at-rest belong to the host deployment, particularly for regulated data. This release must not ingest taxpayer or child personal information. Restrict local access; same-user/root compromise is not prevented by application file permissions.

## Migration behavior

The reviewed consigliere_room_audits table and idx_audit_context index are preserved unchanged, including records, SQL definitions and autoincrement sequence. Dependencies or alternate shapes block migration.

Supported unversioned legacy tables: enterprise_portfolio, remediation_lifecycle, autonomous_resolution_rules, ingestion_journal and notification_outbox. SQLite backup API creates a private pre-migration snapshot (including committed WAL state) and verifies integrity. Source fields are retained in migration_audit; destination fields/IDs and sequence high-water values are reconciled before commit. Historical unverified statuses remain unverified. Legacy rules import disabled pending real approval; invented notification acknowledgements import as LEGACY_UNVERIFIED. Historical float budgets convert per-row with Decimal ROUND_HALF_UP; original floats are retained in the audit. This cannot recover precision already lost in a REAL value.

Unknown tables/columns, custom views/triggers, invalid rows and duplicate open remediations block migration without changing the original schema. These are explicit reviewed-migration dependencies; they are not silently deleted. Migration backups are private, not encrypted: use an encrypted host volume and approved backup retention. Successful structural tests do not establish jurisdictional compliance.

## Rules and real handlers

No seeded action counts as preapproved. Authorized management must configure autonomous_resolution_rules with enabled=1 after approving its scope. Only DEADLINE_LAG is evaluated in this release; budget overruns, feed timeouts and production delays require actual detectors and separate rules. Migration preserves existing rule values and sets enabled=0.

approved_handlers.json is a private file mapping approved action codes to {"path": "/Users/bpa/ForesixaQuant/actions/your_handler.sh", "sha256": "actual SHA256 of file"}. Handler files must be current-user-owned, executable, private (700 is suitable), not symlinks, inside a protected actions directory with no symlink ancestors. The hash must match. These configuration files themselves require trusted local administration. Interpreter/dependency integrity and behavior of each script need separate host review. A path and hash do not prove the script does the right business task.

Handlers receive QZOTIC_INCIDENT_ID for downstream idempotency and a minimal PATH. They must complete synchronously, implement idempotency for their side effects and avoid background children. Scripts run outside write transactions with a 10-second timeout. The runtime kills the process group on timeout. Raw stdout/stderr are not persisted, to avoid leaking data; process exit code is recorded. Exit zero records DEPLOYED (process completed), never VERIFIED_CLEARED. Domain outcome verification is separate.

One host process owns the database lock throughout a pass. It protects cooperating instances, not arbitrary external database writers. Abandoned STAGED actions and CLAIMED notifications transition to UNKNOWN on restart and block automatic action repetition. UNKNOWN/DEPLOYED/FAILED records require authorized outcome reconciliation and documented operator disposition before a new incident can run. No automatic reset command is provided. A crash can occur after an external side effect but before its receipt; this release explicitly does not promise exactly-once external effects.

## Notifications

notification_credentials.json is private host configuration: {"app_token":"your private Pushover application token","user_token":"your private user key"}. No values are shipped here. Not configured means standby without consuming attempts. Sending requires --send-notifications. The adapter uses https://api.pushover.net/1/messages.json with TLS verification and no redirects. A successful provider response records GATEWAY_ACCEPTED only. Phone delivery/acknowledgement is not claimed or tracked. High priority does not guarantee immediate OS presentation.

Only definitive retryable rejections (HTTP 429) enter bounded exponential retries. Permanent rejections fail. Timeouts, invalid responses, server failures or interrupted claims become UNKNOWN and are not automatically resent, because acceptance may have occurred. Gateway-accepted records are never resent by this runtime. UNKNOWN messages require operator reconciliation. This deliberately favors avoiding repeated alerts over guaranteed delivery. Record live API acceptance and actual phone observation during deployment testing.

## Test evidence and limits

run_all_tests.py uses temporary directories/databases, randomly generated temporary keys, harmless local shell scripts and mocked notification transport. It does not write into your Mac repository, send notifications or execute your operational handlers. It covers startup, migrations and rollback, WAL backup restore, full-field mapping, exact cents, timezone validation, authentication, conflicting/expired events, runtime locks, script hashes/permissions, action failure/timeout, crash states, retry backoff, API acceptance and safe CLI behavior.

The included test_results.txt records the executed local test result. This is source-level verification, not a production deployment result or proof that no unknown defects exist. The Mac, operational scripts, live credentials, independent business-outcome review, mobile gateway/hooks, scheduler and broader enterprise engines remain unverified. Those dependencies are not represented as completed work.

Primary API reference: https://pushover.net/api