forkit-ai-footprints 0.2.0 → 0.2.1

package/PRIVACY.md

@@ -11,8 +11,12 @@ Forkit AI Footprints (`forkit-ai-footprints`) is metadata-only by design.
   executable, module, or package-runner evidence; raw commands are not included
   in the report or in the evidence hash;
 - cumulative CPU time, current CPU percentage, and resident memory for supported
-  process trees, held locally for repeated activity classification; raw process
-  entries are never exported;
+  process trees, held locally for repeated activity classification and bounded
+  aggregate per-app resource-history buckets; raw process entries are never
+  exported;
+- the macOS console-lock flag and aggregate HID idle duration, used only to
+  pause observation while the device is locked or has not recently been used;
+  no keys, pointer movements, or input content are recorded;
 - directory entries and file metadata for supported model extensions;
 - loopback runtime API responses from explicitly supported local endpoints.
 - known AI-tool installation/configuration path existence;
@@ -21,7 +25,9 @@ Forkit AI Footprints (`forkit-ai-footprints`) is metadata-only by design.
   supported active tool product name, while model names and all item names are
   excluded from saved HTML and anonymous/global payloads;
 - optional chat/workspace labels supplied explicitly by a cooperating app for
-  local display only; absent cooperation, the fields remain empty;
+  local display only; for Codex, the most recent local catalog display title,
+  recency, and project path may be read, with only the project folder basename
+  retained in memory;
 - macOS major version, CPU architecture, and Node major in aggregate field-test
   results;
 - aggregate counts, exact recognized model-file bytes, architecture, Node major, product version,
@@ -31,7 +37,7 @@ Forkit AI Footprints (`forkit-ai-footprints`) is metadata-only by design.
 
 ## Prohibited collection or export
 
-Census must not retain or emit:
+AI Footprints must not retain or emit:
 
 - raw process commands;
 - process IDs;
@@ -39,7 +45,7 @@ Census must not retain or emit:
 - full filesystem paths;
 - prompts, responses, terminal logs, or source-code content;
 - credentials, cookies, tokens, API keys, or passwords;
-- hostname or Mac display name in Census reports, saved share pages, anonymous
+- hostname or Mac display name in AI Footprints reports, saved share pages, anonymous
   contributions, or global payloads; username, email, and Forkit.dev account
   identity are prohibited everywhere.
 - MCP server names, commands, URLs, environment keys, or environment values;
@@ -48,21 +54,23 @@ Census must not retain or emit:
 
 ## Network boundary
 
-Census may call HTTP(S) endpoints only when the hostname is one of:
+AI Footprints may call HTTP(S) endpoints only when the hostname is one of:
 
 - `localhost`
 - `127.0.0.1`
 - `::1`
 
 Remote endpoints and endpoints containing embedded credentials are rejected.
-Census contains no Forkit.dev login, registry-write, passport-publish,
+AI Footprints contains no Forkit.dev login, registry-write, passport-publish,
 Runtime_C2-write, billing, telemetry-upload, or deployment client.
 
 `forkit-ai-footprints serve` binds only to `127.0.0.1`. Its rescan route
 requires the same page origin and a random in-memory session token. The route
 may return local runtime, model, AI-app, and AI-tool display names to that
 protected local page. It never returns full paths, raw commands, endpoints,
-configuration values, prompts, chat titles, workspace names, or account data.
+configuration values, prompts, or account data. A supported app's recent local
+workflow title and project folder basename may appear only in this protected
+local page and are never written to a report or share/global artifact.
 The numeric guess is compared inside the browser and is not submitted to the
 local server. Start, Stop, Clear history, Scan again, and contribution preview
 all require the same-origin random session token. Closing a browser or native
@@ -71,11 +79,14 @@ window does not stop monitoring; native Quit stops the monitor and local service
 The interactive app keeps `device-journal.json` under the user's macOS
 Application Support directory with directory mode `0700` and file mode `0600`.
 It contains only the sanitized Mac display name, first/last scan timestamps, and
-scan count. It is never placed in the Census report, rescan snapshot, share
+scan count. It is never placed in the AI Footprints report, rescan snapshot, share
 image, saved share page, or anonymous/global contribution. The local monitor
 stream is same-origin and session-token protected. Sampling runs at a one-second
 target interval; durations exclude stopped time and gaps longer than three
-intervals. The stream makes no external request.
+intervals. Observation also pauses while macOS is locked or after 60 seconds
+without user input, and resumes with a new continuous activity block. The lock
+and idle signals remain local and are excluded from reports, share artifacts,
+and global aggregates. The stream makes no external request.
 
 The packaged app uses a native launcher to query Apple DeviceCheck capability.
 The status check makes no network request and writes no key. On a future
@@ -84,11 +95,17 @@ generate one App Attest key and store only its opaque key identifier in the
 device-only Keychain. The current UI and CLI do not invoke enrollment,
 attestation, assertion generation, or upload.
 
+On first launch, the native app asks whether aggregate measurements may be
+prepared for global comparison. The answer is stored locally in macOS user
+defaults as two booleans (asked and allowed). It is not a device identifier and
+is never transmitted. A user who chose “Not now” can reopen the same permission
+from the comparison view.
+
 ## Filesystem identity
 
 Filesystem model identity is derived from metadata such as relative location,
 name, size, and modification time. The absolute path participates only inside a
-local one-way root fingerprint helper and is not included in a Census Report.
+local one-way root fingerprint helper and is not included in an AI Footprints report.
 Model bytes are never read for hashing.
 
 ## Model storage measurement
@@ -106,10 +123,15 @@ and unsupported model locations can make actual disk blocks differ.
 **Working now** requires sustained cumulative CPU-time deltas across repeated
 samples of a supported process tree. Two positive samples enter working and
 three negative samples exit it. Process presence alone remains **Open / idle**.
-This is still not exclusive per-prompt proof. Forkit's own process tree is
-excluded from AI activity and measured separately for CPU, RAM, and bounded
-history overhead. Static hardware metadata describes capability, not use. GPU
-and per-process network attribution remain unavailable; no estimate is used.
+This is still not exclusive per-prompt proof. Supported AI-app CPU/RAM history
+is retained only as bounded local aggregate buckets by app signature/name,
+observed time, active time, average/peak CPU, average/peak memory, peak process
+count, and sample count. It excludes raw process rows, process IDs, commands,
+paths, prompts, responses, and account identity, and it is not included in the
+anonymous/global payload. Forkit's own process tree is excluded from AI activity
+and measured separately for CPU, RAM, and bounded history overhead. Static
+hardware metadata describes capability, not use. GPU and per-process network
+attribution remain unavailable; no estimate is used.
 
 ## Review rule
 
@@ -119,11 +141,12 @@ used as automatic evidence of ownership, safety, provenance, or passport status.
 ## Anonymous contribution boundary
 
 The local app can create an allowlisted schema `2.0` preview only after at least
-600 valid observed seconds. Preview and consent are separate actions. It
+3,600 valid observed seconds. First-launch permission and exact payload review are
+separate actions. The preview
 contains valid seconds, AI-active seconds, activity ratio, supported app count
 and categories, model/loaded/runtime counts, recognized model-file bytes,
 macOS major, architecture, and scanner/runtime schema versions. It excludes
-names, process counts, CPU/RAM values, guess, device identity, local Census ID,
+names, process counts, CPU/RAM values, guess, device identity, local scan ID,
 timestamps, and all item-level records. The CLI and app still have no uploader. A
 separate Forkit.dev aggregate endpoint candidate exists with contribution writes
 disabled by default. That candidate now fails closed without Apple App Attest
@@ -136,7 +159,7 @@ either remains a founder/security release gate.
 `forkit-ai-footprints share-page --output ...` saves a self-contained HTML result only
 after the user supplies an output path. The page contains aggregate counts and
 limitations, not item names, paths, commands, endpoints, configuration values,
-account identity, or the local Census ID. It loads no external assets and makes
+account identity, or the local scan ID. It loads no external assets and makes
 no automatic network requests. Its copy/share controls act only after a user
 click and use aggregate text.
 
@@ -148,3 +171,6 @@ process counts, device/account identifiers, workspace/chat titles, or external
 assets.
 Downloading it or opening the operating system share sheet requires a separate
 user click; AI Footprints does not receive the image.
+Inside the native macOS app, Save PNG, Copy Image, Copy Caption, and Share use a
+loopback-page-to-AppKit bridge restricted to the current local service port. The
+bridge accepts only a validated 1080×1080 PNG and a bounded aggregate caption.

package/README.md

@@ -2,7 +2,7 @@
 
 Forkit AI Footprints is a private, metadata-only view of the models, runtimes,
 and AI agents present on a Mac. The prepared package and command are
-`forkit-ai-footprints`; `forkit-census` remains a temporary binary alias.
+`forkit-ai-footprints`.
 
 It is derived from the discovery lessons in Forkit Connect, but it has a
 different safety boundary: AI Footprints does not authenticate to Forkit.dev and has
@@ -54,11 +54,11 @@ Requirements:
 - npm
 
 ```bash
-git clone https://github.com/arpitasarker01/forkit-census.git
-cd forkit-census
+git clone https://github.com/arpitasarker01/forkit-ai-footprints.git
+cd forkit-ai-footprints
 npm ci
 npm pack
-npm install -g ./forkit-ai-footprints-0.2.0.tgz
+npm install -g ./forkit-ai-footprints-0.2.1.tgz
 forkit-ai-footprints serve
 ```
 
@@ -114,43 +114,50 @@ claims disabled. See [`docs/MACOS_TESTER_GUIDE.md`](./docs/MACOS_TESTER_GUIDE.md
 `share-page` performs the same local scan and writes a self-contained,
 aggregate-only HTML snapshot. It loads no external assets and contains no model
 names, paths, commands, endpoints, configuration values, account identity, or
-Census ID. Its copy/share controls include only the visible aggregate summary
+local scan ID. Its copy/share controls include only the visible aggregate summary
 and run only after a user click.
 
 `serve` binds only to `127.0.0.1`, keeps the report and monitor in memory, and
-opens the AI activity → Guess → Reveal → Share experience. `Scan again` calls a random-token-protected local
+opens the local AI-app activity → Insights → Global vision → Share experience. `Scan again` calls a random-token-protected local
 endpoint. The protected local page can name detected runtimes, models, AI apps,
 and tools. The explicitly created local share image may include the supported
 active tool product name; saved HTML and anonymous/global payloads remain
 aggregate-only.
-The guess remains in the browser page and is never sent to the local server or
-Forkit.dev. Start/Stop controls monitoring explicitly; browser/window closure
-does not stop it, while native Quit stops the monitor and loopback service.
+Start/Stop controls monitoring explicitly; browser/window closure does not stop
+it, while native Quit stops the monitor and loopback service.
 
 The local app also keeps an owner-only device journal containing the sanitized
 Mac display name, first/last scan timestamps, and scan count. This lets the Mac
 resume its local state without placing the device name in a report, saved share
 page, image, anonymous preview, or website payload. The single result view uses
 a token-protected local stream with a one-second target interval. Repeated
-cumulative CPU-time deltas and hysteresis distinguish Working now from Open /
-idle; process presence alone is never activity. It is near-real-time, not zero delay.
+cumulative CPU-time deltas and hysteresis distinguish Active now from Ready;
+process presence alone is never activity. It is near-real-time, not zero delay.
+
+For Codex, the local view can also show the most recent workflow title and the
+final folder name from Codex's private local catalog. This is contextual local
+metadata, not prompt inspection or per-workflow resource attribution. It never
+enters the share image, caption, saved share page, or global payload.
 
 The revealed resource view reports deduplicated recognized logical model-file
-bytes and provider-native loaded-model evidence. The activity view uses private
-process-tree CPU-time deltas and separately displays Forkit's measured CPU,
-resident memory, and bounded-history overhead. None is an energy, token, cost,
-or lifetime-usage measurement.
-
-AI Footprints does not claim prompt or task ownership. **Working now** means
-sustained recent work inside a supported process tree, which may be foreground
-or background. The result does not measure GPU, energy, tokens, cost, disk I/O,
-or per-process network usage.
-
-After revealing the result, `Create share card` renders a 1200×630 PNG entirely
-in the browser. Its result-based line and cards use measured local insights,
+bytes, provider-native loaded-model evidence, current supported-process CPU/RAM,
+and bounded per-AI-app aggregate CPU/RAM history buckets retained locally for the
+observation. The activity view uses private process-tree CPU-time deltas and
+separately displays Forkit's measured CPU, resident memory, and bounded-history
+overhead. None is an energy, token, cost, prompt, task, or lifetime-usage
+measurement.
+
+AI Footprints does not claim prompt, task, or local-model inference ownership.
+**Active now** means sustained recent CPU time inside a supported local AI-app
+process tree, which may be foreground or background. The result does not
+measure GPU, energy, tokens, cost, disk I/O, or per-process network usage.
+
+`Create share card` renders a 1080×1080 (1:1) PNG entirely on the device. Its
+result-based line and cards use measured local insights,
 model-record count, recognized model storage, activity ratio, and the supported
-active tool product name. It can be downloaded or passed to the operating
-system share sheet after an explicit click; no model names, chat/workspace
+active tool product name. Browser controls download or copy it; the installed
+app uses native macOS save, clipboard, and share-sheet actions after an explicit
+click. No model names, chat/workspace
 context, paths, device identity, or scan records are placed in the image or
 uploaded by AI Footprints.
 
@@ -178,26 +185,20 @@ forkit-ai-footprints scan --no-mcp
 ```
 
 CLI flags cannot bypass the required monitoring session. The local UI enables
-an exact schema `2.0` aggregate preview only after 600 valid observed seconds;
-preview and consent remain separate, and no upload transport exists. The
+an exact schema `2.0` aggregate preview only after 3,600 valid observed seconds;
+the installed app asks once on first launch whether aggregate comparison is
+allowed, and no upload transport exists. The
 payload excludes app/model names, process counts, CPU/RAM, chat, workspace,
-repository, device, guess, Census, and account identifiers.
+repository, device, guess, local scan, and account identifiers.
 
 ## Shared core API
 
-Forkit Connect should delegate to the package's public, read-only core rather
-than copy its detector implementation:
-
-```js
-const { runCensus } = require('forkit-ai-footprints');
-
-const report = await runCensus();
-```
-
-The package root also exports the individual metadata detectors, formatters,
-provider adapters, endpoint validation, anonymous-preview builder, and TypeScript
-types. A fresh-install smoke test imports the package root and verifies that an
-all-disabled core scan makes zero external requests and writes no local state.
+Forkit Connect should delegate to this package's public, read-only core rather
+than copy its detector implementation. The package root exports the local scan
+runner, individual metadata detectors, formatters, provider adapters, endpoint
+validation, anonymous-preview builder, and TypeScript types. A fresh-install
+smoke test imports the package root and verifies that an all-disabled core scan
+makes zero external requests and writes no local state.
 
 ## What AI Footprints reports
 

package/STATUS.md

@@ -1,45 +1,75 @@
 # Forkit AI Footprints Status
 
-Last updated: 2026-08-23
+Last updated: 2026-08-27
 
-Version: `0.2.0`
+Version: `0.2.1`
 
 Production classification: `current` for Apple Silicon macOS
 
-Release state: founder-approved public v0.2.0 npm-first release. The npm
+Release state: local v0.2.1 npm-first release candidate. The npm
 bootstrap installs a persistent unsigned local app; Developer ID signing and
 notarization remain future work.
 
 ## What is implemented
 
-- One local experience: AI activity first, Guess → Reveal, an aggregate share
-  card, optional exact global-payload review, Scan again, and technical details.
+- One local experience: local AI-app activity first, deterministic personal
+  insights, a user-initiated link to the Forkit global vision, a square aggregate
+  share card, Scan again, and technical details. The link sends no observation
+  payload.
+- The protected local view names the current device and observation number,
+  keeps the activity explorer on the left, and uses the right observation rail
+  for pulse evidence, deterministic insights, runtime totals, live CPU/RAM,
+  retained local aggregate resource history, recognized model space, verified
+  local runtimes, and per-app filtering. GPU and per-app disk use remain
+  explicitly unavailable rather than estimated.
+- Four compact observation controls on the right switch the left explorer
+  between pulse, runtime, resources, and per-app evidence. Hover text explains
+  each control; selecting a pulse shows its exact local date/time, duration and
+  state, while selecting an app filters the timeline and shows that app's
+  measured runtime, contribution, first/last observation, current CPU/RAM, and
+  retained local aggregate resource-history summary when available.
+- The app shell uses responsive text sizing so labels, values, controls,
+  timeline blocks, inspector cards, and detail rows scale with available window
+  width instead of staying at tiny fixed pixel sizes.
 - Explicit Start/Stop Monitoring with repeated one-second macOS process-tree
   sampling, cumulative CPU-time deltas, two-sample entry and three-sample exit
-  hysteresis, and sleep-gap exclusion.
-- Clear states: **Working now**, **Open / idle**, **Not running**, and **Stopped**.
-  Process presence alone never becomes working activity.
-- One to three deterministic insights from valid measured time: activity share,
-  longest continuous active block, supported-tool workflow, mostly-idle state,
-  and available-but-unused local models. Stop/restart boundaries cannot inflate
-  the longest block.
+  hysteresis, and sleep-gap exclusion. Observation pauses while macOS is locked
+  or after 60 seconds without user input; every invalid interval starts a new
+  continuous activity block when valid observation resumes.
+- Clear states: **Active now**, **Ready**, **Monitoring**, and **Stopped**.
+  Process presence alone never becomes active activity.
+- Durations retain seconds at every scale, including observations longer than
+  one hour.
+- One to three deterministic insights from valid measured time: local AI-app
+  activity share, longest continuous active block, supported-tool workflow,
+  mostly-idle state, and stored local model records. Stop/restart boundaries
+  cannot inflate the longest block.
 - The monitor is owned by the local service, not a browser tab. Closing the
   window does not end a session; stopping preserves the summary; clearing is a
   separate explicit action.
 - A persistent native AppKit/WebKit app installed into the current user's
   Applications folder by a one-time npm bootstrap. Later launches use normal
   macOS surfaces and do not require Terminal.
+- A one-time native first-launch permission for aggregate global comparison,
+  stored only in macOS user defaults. The in-app global action opens the public
+  Forkit AI Footprint global vision section after the observation gate and does
+  not transmit the local result.
 - A native AppKit/WebKit window and retained menu-bar controller with Open,
   Start/Stop, and Quit actions. Closing hides the window without quitting; Quit
   stops the service and has a process-exit fallback so the bundled Node service
   cannot remain orphaned.
 - One English/German localization source drives the app, deterministic insights,
   share caption, menu-bar menu, and close/quit notices.
-- Local-only optional chat/workspace display when a cooperating app explicitly
-  supplies those values. No inference from window titles, folders, prompts, or
-  commands is attempted.
+- Local-only optional workflow/project display. Cooperating apps may explicitly
+  supply it; Codex can also use its most recent private local catalog title and
+  project folder basename. No window-title, prompt, response, or command-text
+  inspection is attempted, and the context never enters share/global artifacts.
 - Forkit's own process tree is excluded from detected AI activity. Its CPU,
   RAM, and bounded-history overhead are measured and labelled separately.
+- Supported AI-app resource history is retained locally only as bounded aggregate
+  per-app buckets: observed/active seconds, average/peak CPU, average/peak RAM,
+  peak process count, and sample count. It is not prompt/task attribution and is
+  excluded from share/global payloads.
 - Exact recognized logical model-file bytes for supported roots, with hard-link,
   symlink, overlapping-root, Hugging Face snapshot, and Ollama content-addressed
   deduplication.
@@ -48,7 +78,7 @@ notarization remain future work.
   valid `/api/ps` response.
 - A schema `2.0` candidate global aggregate based on valid observed seconds and
   AI-active seconds. It excludes names, process counts, paths, commands, chat,
-  workspace, device identity, guess, and Census ID. Review and consent are
+  workspace, device identity, guess, and local scan ID. Review and consent are
   separate; upload transport remains disabled.
 - A 1080×1080 local share card with Share, Save PNG, Copy Image, and Copy
   Caption controls. It contains only measured totals and supported tool names.
@@ -77,19 +107,23 @@ notarization remain future work.
   p95 CPU**, about **53.3 MB current RAM**, **117.1 MB maximum RAM**, and **627
   bytes** of bounded serialized history at the final payload sample.
 - A final source-identical bundled-app observation reached **63.3 seconds** of
-  valid time and **62.1 seconds** AI-active (ratio **0.981**), producing: “Codex
-  was working during 98% of your observation.”, “Your longest continuous
-  AI-active period was 1m 1s.”, and “5 local models are available, but none ran
-  during this observation.”
-- A separate real session crossed the 10-minute gate at exactly **600 valid
-  seconds** and **598 AI-active seconds**. Only then did the local comparison
-  preview become available; no transport was enabled.
+  valid time and **62.1 seconds** AI-active (ratio **0.981**). The deterministic
+  evidence reports the supported app activity share, longest continuous signal,
+  and stored local model records without attributing prompts or tasks.
+- A separate earlier real session crossed the previous 10-minute gate at exactly
+  **600 valid seconds** and **598 AI-active seconds**. The current global
+  comparison candidate now requires **3,600 valid seconds** before the local
+  preview becomes available; no transport is enabled.
 
 ## Validation completed locally
 
-- TypeScript build and the complete local test suite.
-- Curated agent detector corpus: **58/58** fixtures, 26 positive and 32 negative,
-  with zero fixture errors. This is conformance evidence, not field accuracy.
+- TypeScript build and the complete local test suite: **119/119** tests passed.
+- Deterministic active → idle/locked → resumed lifecycle coverage confirms that
+  paused time changes neither observed nor AI-active seconds and cannot bridge
+  the longest continuous activity block.
+- Curated agent detector corpus: **68/68** fixtures, 30 positive and 38 negative,
+  with zero fixture errors and fixture precision/recall/accuracy of 1.0. This is
+  conformance evidence, not field accuracy.
 - Isolated packed-package installation/import/CLI smoke.
 - Native Swift compilation, bundled CLI/version smoke, bundled official Node
   checksum, App Attest capability probe, and unsigned `.app`/`.pkg` build.
@@ -100,9 +134,10 @@ notarization remain future work.
 - Accessibility evidence placed the retained 24×24 status item at `y=-59` while
   macOS auto-hid the menu bar and at `y=3` after revealing the bar. Its help text
   was “Forkit AI Footprint” and its complete localized menu was exposed.
-- Real-browser QA in English and German for the local monitor, Guess → Reveal,
-  correct GB/GiB labels, deterministic captions, 1080×1080 PNG export, image
-  clipboard/share payloads, and the one-page Forkit.dev installation/global page.
+- Real-browser QA in English and German for the Activity Explorer, interval
+  evidence, reconnect persistence, stable system colors, correct GB/GiB labels,
+  deterministic captions, 1080×1080 PNG export, image clipboard/share payloads,
+  and the one-page Forkit.dev installation/global page.
 - Forkit.dev production website build and registry AI Footprints route tests.
 
 ## Intentionally not enabled or not yet field-validated
@@ -114,6 +149,9 @@ notarization remain future work.
   test, or clean external-Mac installation test.
 - No representative multi-device macOS field-accuracy result and no Intel Mac
   release claim.
+- The live Mac reproduced the HID-idle paused state while monitoring remained
+  active. The saved scorecard, timeline, insights, and stable system colors
+  remained visible and unchanged through the paused state and reconnect.
 - App Attest reports unsupported on this macOS 26 device, so this Mac cannot
   produce a verified global contribution under the proposed proof policy.
 - No prompt, task, token, energy, cost, GPU, disk-I/O, or per-process network
@@ -126,8 +164,9 @@ runner matches and verified runtime identities are strong implementation rules,
 but one real Mac and a curated fixture corpus cannot establish a global
 precision/recall percentage. Model storage is exact only for recognized files
 inside supported roots when `storage_complete=true`; it is not whole-disk AI
-storage or APFS physical allocation. **Working now** means sustained recent CPU
-time in a supported process tree and nothing more.
+storage or APFS physical allocation. **Active now** means sustained recent CPU
+time in a supported local AI-app process tree and nothing more; it does not
+claim that a cloud model is running locally.
 
 ## Smallest release gate
 

package/dist/activity-page.d.ts

@@ -0,0 +1,13 @@
+import type { AiFootprintPageOptions, CensusShareSnapshot, LocalScanView } from './share-page';
+import { type UiLocale } from './localization';
+export interface ActivityApplicationPageInput {
+    locale: UiLocale;
+    snapshot: CensusShareSnapshot;
+    view: LocalScanView | null;
+    rescan: AiFootprintPageOptions['rescan'];
+    device: string;
+    brand: string;
+    shareLogo: string | null;
+}
+export declare function renderActivityApplicationPage(input: ActivityApplicationPageInput): string;
+//# sourceMappingURL=activity-page.d.ts.map