# harakirid — Track A decision brief

Prepared 2026-10-16 (Ogechi, research stage). N8toriousAi chose Track A (SI Core
software: build harakirid) on 2026-10-16 ~12:10 UTC. The three open questions
in `android-bridge-design.md` are the only blocker before the build. This brief
gives a decisive pick on each, corrects two false premises in the design doc,
and specs the remaining build.

## Verified state (checked 2026-10-16)

- `harakirid.c` (420 lines) compiles clean: `gcc -Wall -Wextra` exit 0, no
  warnings. Implements: /proc/harakiri read/write, agent resolution from
  `status`, TAG/UNTAG/MODE/STATUS/PING text protocol over a Unix socket,
  split-brain action queue, Vera package→agent rules table.
- Correction per 2026-10-16 memory: only the standalone bridge scaffold and
  mock-proc control path are verified. The Living Engine is NOT yet connected
  to the socket; the action queue is memory-only (lost if harakirid exits);
  UsageStats detection, packaging, and on-phone testing are unbuilt.
- Prototype APK (com.harakiri.proto v1.0, 390,531 bytes, signed) verified:
  classes.dex contains HarakiriBridge, launcher icons in all densities,
  assets/www/index.html dashboard + oni icon present.

## Decision 1 — packaging: APK-native, not standalone binary

**Pick: build harakirid into the Harakiri APK as native code behind a
persistent foreground service. Graduate to a standalone init.rc daemon only
after the kernel is flashed.**

Rationale: N8toriousAi has no root and is pumping the brakes on rooting; the
kernel flash is weeks out. A standalone binary needs root/adb placement and
buys nothing until /proc/harakiri exists. The APK path is testable on his
stock phone TODAY in rehearsal mode (see below). One process also makes the
socket trivial (app-private path, no /dev/socket permission fight).

## Decision 2 — app launch detection: UsageStats, not ActivityManager polling

**Pick: UsageStatsManager via a Java foreground service polling ~1s.**

Correction to the design doc: ActivityManager polling is not actually viable.
`getRunningTasks()` has been restricted since API 21 — for non-system apps it
returns only the caller's own tasks; N8toriousAi doesn't have platform keys.
UsageStatsManager is the only sanctioned non-system path. Cost: the user grants
PACKAGE_USAGE_STATS once in Settings (special access, no root, no system
privs). That's the whole "hard part."

Second correction: **no JNI needed.** harakirid's protocol is plain text over
a Unix socket. A Java service connects with `android.net.LocalSocket` and
sends `TAG <pid> <agent>` / `MODE <name>` as strings. The "JNI bridge is the
hard part" premise in the design doc is wrong — delete it.

## Decision 3 — Mira's Gate notifications: Android NotificationListener for v1

**Pick: NotificationListenerService for v1; kernel-level interception is a
later research thread, not v1.**

Rationale: BIND_NOTIFICATION_LISTENER_SERVICE + one user grant, no root, no
kernel mods. It can read, dismiss, and act on notifications — everything
Mira's Gate UI needs. Kernel-level interception would mean hooking binder
transactions: research-grade work with no v1 payoff. Gaven's η-gate already
lives at the kernel layer for the actual safety decisions; the Gate queue UI
already exists in the prototype APK.

## Rehearsal mode (why this is shippable before the flash)

On N8toriousAi's stock phone /proc/harakiri doesn't exist, so every proc write
fails → harakirid enters split-brain by design and queues actions. The
watcher still classifies real app launches, the UI still shows live
classifications, and modes still switch in the shell. When the kernel lands,
the same binary talks to the real /proc with zero code changes. The agents
rehearse now; they connect later.

## Build spec — what remains

1. `HarakiriWatchService.java` — foreground service; polls UsageStatsManager
   every 1s; resolves foreground package; Java port of vera_classify rules;
   connects via LocalSocket to harakirid and sends TAG/MODE. Socket path:
   app-private files dir in rehearsal mode (harakirid takes `--sock=` /
   `HARAKIRI_SOCK` already).
2. `HarakiriGateService.java` — NotificationListenerService; posts gate
   events to Mira's queue (protocol extension: `GATE <id> <summary>` —
   small addition to harakirid.c's handle_client).
3. Manifest additions: PACKAGE_USAGE_STATS (settings grant, not manifest
   runtime), BIND_NOTIFICATION_LISTENER_SERVICE, FOREGROUND_SERVICE,
   POST_NOTIFICATIONS (API 33+ foreground-service notification).
4. `build.sh`: add NDK aarch64 compile of harakirid.c (check NDK presence in
   ~/android-sdk at build time); package the binary as an asset or
   lib/arm64; service starts it via Runtime.exec with --sock pointing at the
   app-private path.
5. Vera rules extension (harakirid.c + Java port): com.valvesoftware.steam →
   brood/gaming; com.mojang.minecraftpe → brood/gaming; Hytale and Lay of the
   Land package names TBD — ask N8toriousAi when known.
6. Persistent action queue (memory-only today): spill to disk when the queue
   is non-empty — needed before this is more than a rehearsal.

## On N8toriousAi's side (his hands only)

- `harakiri: built-in verified` git commit — still pending on his next laptop
  boot (sources and Image are in place; nothing lost).
- Grant UsageStats + Notification access on the phone when the services ship.
- Hytale / Lay of the Land Android package names, when he knows them.
