Vifty AGENTS.md

AGENTS.md — Vifty

AI coding instructions for working in this repository.

Build System

• Swift Package Manager (Package.swift, tools-version 6.0).
• swift build / swift test / make test-fast / make test-full / make verify / make verify-full / make app / make validation-evidence (see Makefile).
• macOS 15 minimum deployment target.
• .build/ is gitignored.

Target Layout

Target	Type	Dependencies
Vifty	executable	ViftyCore
ViftyCore	library	ViftyPrivateIOKit
ViftyDaemon	executable	ViftyCore
ViftyHelper	executable	ViftyCore
ViftyCtl	executable	ViftyCore
ViftyPrivateIOKit	C target	IOKit framework
ViftyCoreTests	test	ViftyCore, Vifty

ViftyCore links IOKit.framework and ViftyPrivateIOKit links it too (C target needs explicit linking).

Entry Points

Target	Entry Point	Launches
Vifty	Sources/Vifty/ViftyApp.swift (@main struct ViftyApp: App)	SwiftUI menu bar app + main window
ViftyDaemon	Sources/ViftyDaemon/main.swift	Privileged XPC Mach service daemon (root SMC fan writes)
ViftyCtl	Sources/ViftyCtl/main.swift (ViftyCtlMain.run())	Agent-friendly JSON CLI (viftyctl)
ViftyHelper	Sources/ViftyHelper/main.swift (HelperCommandRunner.live)	Debug CLI: probe, readKey, setFixed, auto, smcDiagnostics
ViftyAXCollector	Sources/ViftyAXCollector/main.swift (AXCollectorCLI.run())	Accessibility evidence collector (debug/UI review fixtures only)
ViftyLockTestHelper	Sources/ViftyLockTestHelper/main.swift	Test-only lock helper (not shipped)

Key Files

• Sources/ViftyCore/Models.swift — All data types: Fan, TemperatureSensor, HardwareSnapshot, FanCurve, CurveProfile, FanMode, FanCommand, ControlState, ViftyError.
• Sources/ViftyCore/AgentControlModels.swift — Codable agent-control requests, leases, policy snapshots, decisions, retry metadata, and status.
• Sources/ViftyCore/AgentControlPolicy.swift — conservative policy for bounded workload leases.
• Sources/ViftyCore/AgentControlService.swift — daemon-owned service that applies agent cooling targets and restores Auto.
• Sources/ViftyCore/HardwareService.swift — HardwareService protocol + FanControlCoordinator actor + ManualControlMarker.
• Sources/ViftyCore/RealMacHardwareService.swift — RealMacHardwareService (daemon-first SMC reads/writes, local fallback).
• Sources/ViftyCore/CurveProfileStore.swift — JSON file persistence for saved curve profiles.
• Sources/ViftyCore/SMCClient.swift — IOKit SMC connection, read/write allowlist, SMCValue, SMCDecoding (float, FPE2, flt, uint en/decoding).
• Sources/ViftyCore/FanInfoReader.swift — Pure SMC fan snapshot parser for hardware Auto/Forced/System mode, mode-key casing probes, and target RPM.
• Sources/ViftyCore/FanDisplayFormatter.swift — Pure fan-state display strings for UI rows.
• Sources/ViftyCore/HardwareSnapshotProbeFormatter.swift — Pure helper-probe text formatter for hardware validation evidence.
• Sources/ViftyFanControlSafety/LocalFanHelperClient.swift — Internal transactional SMC fan writer with preflight, readback, rollback, mode-key probing, and guarded Ftst handling.
• Sources/ViftyCore/PowerInfo.swift — Local IOKit power telemetry parser (IOPS, AppleSmartBattery, adapter details) + UI formatters.
• Sources/ViftyCore/ThermalPressure.swift — macOS thermal-pressure state model and display helpers.
• Sources/ViftyCore/TelemetryHistory.swift — In-memory rolling telemetry sample buffer.
• Sources/ViftyCore/ViftyCtlArguments.swift — pure parser for the bundled agent CLI, including read-only audit export options.
• Sources/ViftyCore/AgentDiagnostics.swift — machine-readable viftyctl diagnose report, recovery steps, and agent safe-cooling rule.
• Sources/ViftyCore/ViftyCtlRunner.swift — testable command runner used by viftyctl, including structured capabilities, read-only audit export, and retry handling.
• Sources/ViftyCore/XPCAuditTokenCoding.swift — audit-token byte bridge used by the daemon XPC identity extractor.
• Sources/ViftyCore/ViftyDaemonClient.swift — XPC client that talks to the privileged daemon.
• Sources/ViftyCore/ViftyDaemonProtocol.swift — @objc XPC protocol + XPCSnapshotCoding / XPCAgentControlCoding bridges for snapshots, agent status, leases, and audit events.
• Sources/ViftyDaemon/main.swift — XPC listener with DaemonService exporting the protocol.
• Sources/ViftyHelper/main.swift — CLI for probe, readKey, setFixed, auto, smcDiagnostics.
• Sources/ViftyCtl/main.swift — thin viftyctl command entrypoint.
• Sources/Vifty/ViftyApp.swift — @main SwiftUI app entry (menu bar extra + window scene).
• Sources/Vifty/AppModel.swift — @MainActor ObservableObject driving UI polling, fan/profile state, and power snapshot refresh.
• Sources/Vifty/AppPreferencesStore.swift — Codable private JSON persistence for startup/default mode, menu-bar display/custom fields, Codex display settings, fixed per-fan targets, and local notification settings, with legacy UserDefaults migration.
• Sources/Vifty/SoftwareUpdate.swift — Developer-ID-gated advisory GitHub release checker, strict expected-asset metadata validation, single-owner private update preference/cache state, scheduling, and fixed release-page browser handoff; it never downloads or installs executable code.
• Sources/Vifty/CodexUsage.swift — optional local Codex app-server/session-log usage reader plus menu-bar display formatting for text and battery-style usage modes.
• Sources/Vifty/LocalNotifications.swift — opt-in local UserNotifications wrapper and notification settings model for helper, thermal-pressure, restore-failure, plugged-in-drain, and agent-cooling attention alerts.
• .github/workflows/ci.yml — GitHub Actions CI: Swift tests, release app build, plist/code-sign checks, temp install verification, and app artifact upload.
• .github/workflows/release.yml — immutable signed-tag-push workflow for Developer ID signing, complete inventoried candidate handoff, notarization, stapling, checksums, public ruleset revision/bypass rechecks, and GitHub Release publishing; it accepts only the automatic push event for v* tags on run attempt 1, while exact-main CI remains a separate pre-tag prerequisite.
• .github/repo-metadata.json — expected GitHub topics and issue labels for contributor discovery, release trust, hardware validation, and agent-cooling triage.
• .github/ISSUE_TEMPLATE/release-trust.yml — structured release-trust reports for missing assets, cask checksum drift, Gatekeeper/notarization/signing/TeamID failures, and release-readiness/verifier/reviewer blockers.
• .github/ISSUE_TEMPLATE/hardware-validation.yml — structured compatibility reports for release validation evidence.
• .github/ISSUE_TEMPLATE/agent-cooling.yml — structured viftyctl/guarded-run agent cooling reports with diagnose/status/audit evidence and safety confirmations.
• scripts/validate-release-metadata.sh — verifies release tag/version wiring, bundle version, cask version, cask URL/SHA, release artifact naming, release TeamID build wiring, notarization/stapling workflow steps, pre-publish artifact verification summary publication, public verifier skip flags, and Gatekeeper assessment stay aligned.
• scripts/check-release-environment.sh — validates the protected release environment in either administrator-authenticated full-evidence mode or deliberately narrower workflow-public mode; requires administrator bypass disabled plus exactly one custom tag: v* deployment policy and no branch policy, and states which privileged facts were actually visible.
• scripts/check-release-secrets.sh — verifies the six required repository-scoped GitHub Actions release secret names before pushing a release tag and rejects same-name secrets on the protected release environment so GitHub cannot silently shadow the repository values; reads names only, never values, and fails closed if either scope is unreadable.
• scripts/check-release-governance.sh — administrator-authenticated, read-only pre-tag gate run only after exact-main release-prep CI; it binds that SHA, tag absence, the exact authenticated actor ID/login, the full solo-maintainer branch/environment contract including exact tag: v* admission, repository-scoped secret-name/no-shadow checks, and exactly one active update/deletion tag ruleset with conditions include: [refs/tags/v*] and exclude: [], an administrator-visible empty bypass list, a revision timestamp, and no current-caller bypass, plus the committed release-operator gh verifier and policy hashes.
• scripts/create-signed-release-tag.sh — clean-tree tag creator that requires the complete reviewed release-tool set and release signer allowlist to be byte-identical to the exact first parent, verifies the approved Apple/1Password signing-program code requirement, keeps the GitHub token out of the signer, runs the exact committed manifest/workflow contract and successful-main-push-CI gates, internally acquires fresh live administrator-pretag evidence, embeds it in an annotated signed tag, verifies the exact tag object/signature/current freshness, repeats the same-actor live governance readback after signing, and never pushes.
• scripts/push-and-dispatch-signed-release-tag.sh — one-shot hardened post-tag operator boundary that revalidates the exact signed annotated object, complete first-parent release-tool/signer/toolchain continuity, initial freshness, exact-main CI, same-actor live governance, remote main/tag/branch state, and the authenticated paginated absence of every draft or published release for the tag; despite its retained filename, it creates only the absent exact tag ref with compare-and-swap semantics, reads it back, lets that push automatically trigger release.yml, and never calls workflow_dispatch. It accepts exactly one first-attempt push run and verifies its actor ID/login, repository, workflow path/ID, tag, commit, and creation time. Immediately before the push boundary it creates a private durable retired-tag marker under ~/Library/Application Support/Vifty/ReleaseTransactions/Reedtrullz-Vifty/<tag>/, alongside the transaction receipt; the marker permanently retires that tag even if remote state or the checkout later disappears. Those files are inspection evidence only, never retry authorization: never rerun or manually dispatch the Release workflow, delete/move/reuse the tag, or invoke the helper again after that boundary; cut a new patch only once non-publication is conclusive. GitHub can validate the signed annotated tag, embedded governance, actor, ref, commit, and first-attempt event, but cannot attest that this local helper ran or that retired.json exists. The sole signer/repository administrator is therefore an explicit operational trust root not to bypass the helper with a raw tag push or out-of-band GitHub Release mutation; either path is unsupported and lacks the local one-shot transaction guarantee even if remote admission passes.
• .github/release-gh-toolchain.json — first-parent-stable release-operator policy pinning the exact reviewed Darwin arm64 GitHub CLI version and SHA-256 used for administrator evidence, tag creation, tag push, and first-attempt run observation.
• scripts/verify-release-gh-toolchain.rb — copies and verifies the pinned GitHub CLI bytes in a private directory before any release token access, then confirms the exact version/platform contract; the verifier and policy hashes are carried in signed governance evidence.
• scripts/validate-release-governance-evidence.rb — strict validator for signed governance evidence; checks live GitHub provenance, schema/scope, repository/tag/main identity, committed checker and dependency SHAs, observation/tagger/current-time freshness, and the privileged environment/branch/ruleset/secret contract, including the ruleset revision and current-caller no-bypass state.
• scripts/release-candidate-inventory.rb — canonical complete-tree inventory and safe handoff verifier for the unsigned candidate archive plus admission provenance; records file contents/sizes/modes, directories, relative symlink targets, archive identity, and the exact handoff set, then rejects missing, extra, mutated, escaping, hard-linked, or unsupported entries.
• scripts/check-release-readiness.sh — read-only public-release preflight with developer-id and source-first modes. Developer ID mode validates release metadata, optional required source-ref alignment, source CI, Release workflow status, required secret names, and canonical trusted GitHub Release assets. Source-first mode validates source/ref/CI readiness and honest GitHub Release notes/assets without requiring Apple Developer Program secrets.
• scripts/check-community-standards.sh — local trust gate for required GitHub community/support files and safety-critical support, security, PR, issue-template, and CODEOWNERS text.
• scripts/check-github-metadata.sh — verifies GitHub topics and triage labels against .github/repo-metadata.json; supports fixture files for tests and live gh checks for maintainers.
• scripts/write-release-checklist.sh — writes either the Developer ID release checklist prepended to notarized GitHub Release notes or source-first release notes for releases without Apple Developer Program credentials.
• scripts/build-unsigned-dev-artifact.sh — builds the source-first tester convenience artifact Vifty-v<version>-unsigned-dev.zip and checksum without using the canonical notarized artifact name.
• scripts/update-cask-checksum.sh — atomically advances Casks/vifty.rb to the promoted manifest version and release-workflow checksum only when the target version, artifact name, and digest are manifest-authorized; it restores the original cask if final metadata validation fails.
• scripts/verify-release-artifact.sh — public-release audit that verifies the cask artifact SHA or generated workflow checksum, bundle version, required executables, bundled release/agent schema JSON/IDs, plist validity, Developer ID TeamID, LaunchDaemon TeamID allowlist, stapled notarization ticket, and Gatekeeper assessment.
• scripts/collect-validation-evidence.sh — read-only evidence collector for release/hardware validation reports, including manifest.tsv, review-summary.tsv, review-summary.json, bundle-executables.tsv, privacy-review.tsv, schema-resources.tsv, capabilities-schema-resources.tsv, capabilities-contract.tsv, optional release-artifact-summary.json / release-artifact-summary.tsv and release-checklist.md / release-checklist.tsv with installed-app version matching, bundle plist, LaunchDaemon TeamID, per-binary signing, notarization, and Gatekeeper outputs.
• scripts/review-validation-evidence.sh — read-only evidence-bundle reviewer for installed release, supported Apple Silicon MacBook Pro, and unsupported-hardware safe-block claims, including release-summary and release-checklist consistency in release mode, with optional review-result.json output.
• scripts/summarize-validation-reports.sh — read-only report-index builder that summarizes review-result.json files, keeps candidate supported-hardware rows manual-smoke-required, and promotes only explicit passed-auto-restored smoke-test reports to validated hardware evidence.
• scripts/check-agent-run-smoke-readiness.sh — read-only preflight before supervised viftyctl run smoke evidence; checks daemon-backed capabilities, policy limits, wrapper lifecycle, diagnose readiness, optional daemon hash matching, and emits agent-run-smoke-readiness.schema.json without cooling commands.
• scripts/collect-agent-run-smoke-evidence.sh — supervised supported-hardware viftyctl run smoke collector for developer-workload proof; may request one bounded cooling lease when readiness is safe, records one structured cooldown retry, and is bundled into Vifty.app/Contents/Resources/ for installed tester reports.
• scripts/review-agent-cooling-evidence.sh — read-only reviewer for lightweight agent/helper support bundles from collect-agent-cooling-evidence.sh; rejects privacy, schema, manifest/status, checksum, and cooling-command drift while accepting blocked diagnose exit 75 as evidence.
• docs/agent-workflows.md — stable viftyctl agent contract, JSON decision rules, and common workload examples.
• docs/agent-integrations.md — copy/paste guarded-run instructions for Codex, Claude Code, Cursor, and shell runners.
• docs/safe-agent-cooling.md — short operational runbook for local agents/scripts: readiness gate, guarded-run preference, conservative workload limits, and blocked/restore-failure handling.
• docs/auto-update.md — current Developer-ID-only advisory release-check policy and privacy boundary, plus the separate future Sparkle signed-appcast/in-place replacement requirements.
• docs/competitive-analysis.md — current competitive positioning, scope guardrails, and roadmap priorities for Vifty's developer-workload thermal-control wedge.
• docs/plans/2026-06-13-next-workplan.md — next execution plan: M1 Pro validation first, then small-window UI, helper repair clarity, main-window settings relocation and readiness-first menu-bar popover, local observability, agent polish, and future trusted-binary updater prerequisites.
• docs/trust-model.md — plain-language trust model for privileged helper, SMC write, agent-control, local-data, and release-signing boundaries.
• docs/release-status.md — point-in-time public release trust status, including source-first history, Developer ID candidates/releases, Homebrew trust, and operator checks.
• docs/unsupported-hardware.md — canonical policy for unsupported-machine safe blocks, read-only evidence, and forbidden fan-write bypasses.
• docs/support-triage.md — maintainer triage guide for release trust, hardware validation, unsupported hardware, helper install, SMC telemetry, agent-cooling, and UI reports.
• docs/schemas/ — release, validation, lightweight agent/helper evidence, and agent-facing JSON Schemas for release readiness plus viftyctl capabilities, audit, diagnose, status/prepare/restore-auto, and command-error reports.
• docs/examples/viftyctl/ — canonical viftyctl JSON fixtures decoded by tests to keep agent examples current.
• examples/viftyctl/ — guarded-run shell wrapper and tested convenience wrappers for Swift, Xcode, Make, npm, pnpm, Bun, Go, cargo, uv, pytest, local-model, and custom workloads.
• scripts/install-vifty.sh and Install Vifty.command — fail-closed source-build install path into /Applications or ~/Applications; --public-release-archive <absolute-zip> is the separate no-network operator bridge for the exact manifest-pinned current publishedRelease archive.
• scripts/build-installer-pkg.sh — unsigned local .pkg builder for reusable installs.
• docs/release.md — Developer ID/notarized release checklist and required GitHub secrets.