@aitne-sh/aitne 0.1.8 → 0.1.10

package/agent-assets/docs/troubleshooting/wiki-ingest-full-blocked.md

@@ -7,95 +7,167 @@ aliases:
   - ingest full refused
   - wiki approval pending
   - wiki dirty tree refused
+  - compile full uncommitted changes
 category: troubleshooting
 summary: |
-  `!compile full` either refused with "uncommitted changes" (git
-  pre-compile gate) or returned "Sent for approval" (cost gate).
+  `!compile full` stopped before running and replied with one of three
+  things: "uncommitted changes" (the git pre-compile gate), "Sent for
+  approval" (the cost gate), or "Wiki is not enabled" (no workspace).
   This entry tells you how to clear each branch.
-section: wiki-ingest-full-blocked
+section: troubleshooting
 tags:
   - troubleshooting
   - wiki
   - cost
   - git
+  - approval
 status: stable
 ask_examples:
   - Why did !compile full refuse to run?
   - Where do I approve a pending wiki compile?
   - Why does !compile full want a clean git tree?
+  - What does "Sent for approval" mean after !compile full?
 locale: en-US
 created: 2026-05-12
-updated: 2026-05-12
+updated: 2026-05-28
 keywords:
-  - wiki ingest blocked
-  - ingest cost gate
-  - ingest approval
+  - wiki compile blocked
+  - compile cost gate
+  - compile approval
   - full rebuild blocked
+  - uncommitted changes
+process_keys:
+  - wiki.compile
+api_endpoints:
+  - GET /api/approvals
+  - POST /api/approvals/:id/approve
 related:
   - features/wiki/commands
+  - features/wiki/cost-and-approval
   - guides/budget-and-cost-for-wiki
   - features/wiki/overview
+prerequisites:
+  - features/wiki/overview
 ui_anchors:
   - /settings/wiki
-  - /approvals
+  - /
 ---
 
 # `!compile full` Is Blocked
 
 ## What You See
 
-You ran `!compile full` and the bang reply says either:
+You ran `!compile full` and the bang reply was one of these. Jump to the
+matching section:
+
+- **"the external vault has uncommitted changes"** — the git pre-compile
+  gate. See [Uncommitted Changes](#uncommitted-changes).
+- **"Sent for approval"** — the cost gate. See [Sent for
+  Approval](#sent-for-approval).
+- **"Wiki is not enabled"** — no workspace exists. See [Not
+  Enabled](#not-enabled).
+
+## Uncommitted Changes
 
-- "Cannot run `!compile full` — the external vault has uncommitted
-  changes."
-- "Sent for approval. Open `/settings/wiki` → Approvals to confirm
-  and the compile will start."
+The full reply is:
 
-## "Uncommitted Changes"
+> Cannot run `!compile full` — the external vault has uncommitted
+> changes. Please commit or stash first. Dirty paths: …
 
-This is the **git pre-compile gate** firing. Aitne refuses to start
-`!compile full` on an external git-tracked vault with a dirty working
-tree because the pre-compile snapshot it would create can no longer
-be a clean baseline.
+This is the **git pre-compile gate** firing. Before a full rebuild,
+Aitne wants to take a clean pre-compile snapshot commit so you can revert
+the whole compile in one step. It refuses to start on an external
+git-tracked vault whose working tree is dirty, because that snapshot
+would no longer be a clean baseline.
 
 To proceed:
 
 1. `git -C <vault> status` — review the dirty paths Aitne listed.
 2. Commit or stash them: `git add -A && git commit -m "wip"` or
    `git stash -u`.
-3. Re-run `!compile full`. On a clean tree Aitne runs
-   `git add -A && git commit -m "aitne wiki: pre-compile snapshot <ts>"`
-   automatically.
-
-If you don't want the auto-commit, disable **Auto-commit before
-`!compile full`** in **Settings → Wiki** (only visible for
-git-tracked external vaults). Aitne will then run without taking a
-snapshot — and the approval-gate DM will explicitly say "no git
-backup taken".
-
-## "Sent for Approval"
-
-The cost estimator's pessimistic bound (`2× expected`) exceeded the
-per-workspace approval threshold (default $2.00). To approve:
-
-1. Open the dashboard.
-2. Go to **Settings → Wiki → Approvals** (or hit the **Approvals**
-   notification card directly).
-3. Review the estimate. Click **Approve** to run, **Deny** to skip.
-
-If the estimate looks wrong, you have three levers:
-
-- **Lower the avg input tokens** — the default 1500 is conservative
-  for short raw notes; check whether your typical raw note is
-  smaller.
-- **Switch the `wiki.compile` model** to a lite tier in the
-  per-command selector. Sonnet's per-token cost is the dominant
-  variable.
-- **Raise the threshold** in **Settings → Wiki** so routine
-  recompiles don't queue an approval.
-
-## "Not Enabled"
-
-If `!compile full` replies "Wiki is not enabled", you have no active
-workspace row. Run **Enable Internal Workspace** (or **Probe &
-Create External**) on `/settings/wiki` first.
+3. Re-run `!compile full`. On a clean tree Aitne commits the snapshot
+   itself (`aitne wiki: pre-compile snapshot <ts>`) before the compile
+   starts, and the reply echoes the short SHA.
+
+If you don't want the auto-commit, turn off **Auto-commit before
+`!compile full`** on `/settings/wiki` (the toggle only appears for
+git-tracked external vaults). Aitne then runs without taking a snapshot,
+and the estimate reply says `pre-compile git snapshot: disabled by
+setting`.
+
+> Internal-mode wikis are not git-tracked — they snapshot through
+> `md_file_snapshots` instead, so this gate never fires for them.
+
+## Sent for Approval
+
+The full reply ends with:
+
+> Sent for approval. Open `/settings/wiki` → Approvals to confirm and the
+> compile will start.
+
+This is the **cost gate**. Before running, Aitne estimates the compile
+cost (pure on-disk arithmetic — no agent session is spent). The estimate
+DM looks like this:
+
+```
+Full compile estimate for `my-wiki`:
+- raw notes: 42
+- est. input tokens: 51,300
+- cost range: $0.08 (optimistic) – $0.31 (pessimistic), expected $0.15
+- approval threshold: $2.00
+```
+
+If the **pessimistic** bound (`2× expected`) exceeds the per-workspace
+approval threshold (default **$2.00**), the compile is queued for
+approval instead of running.
+
+### Approve or Deny
+
+The queued request shows up as a **pending approval** on the dashboard.
+Open the dashboard overview (the home page `/`, also reached via the
+`/approvals` shortcut) and use the **pending approvals** card:
+
+- Click **Approve** to run the compile. Aitne re-checks the git tree and
+  takes the pre-compile snapshot at that moment (so declining leaves your
+  git log clean).
+- Click **Deny** to drop it.
+
+You can also approve from your DM channel by replying `yes` to the
+request.
+
+### If the estimate looks too high
+
+You have three levers, all on `/settings/wiki`:
+
+- **Raise the threshold.** The **Approval threshold for `!compile full`**
+  field controls when a compile queues for approval. Bump it if routine
+  recompiles keep stalling on a confirmation you'd always grant.
+- **Use a cheaper model.** In the **Commands & models** section, point
+  `wiki.compile` at a lite-tier model. It defaults to the medium tier
+  (Claude Sonnet 4.6), whose per-token cost is the dominant variable in
+  the estimate.
+- **Trim the raw layer.** The estimate scans `10_raw/` and approximates
+  tokens per file from on-disk content, so the cost tracks the actual
+  size of what you're compiling. Compiling fewer or shorter raw notes
+  lowers the bound directly.
+
+> The estimate is a heuristic (≈4 chars per token for prose, denser for
+> CJK), bracketed `0.5×`–`2×`. It is intentionally cheap rather than
+> exact — close enough to gate spend without burning a session to
+> measure it.
+
+## Not Enabled
+
+If the reply is:
+
+> Wiki is not enabled. Open `/settings/wiki` and enable the internal
+> wiki workspace first.
+
+you have no active workspace row. On `/settings/wiki`, either click
+**Enable internal wiki** to create the built-in workspace, or point Aitne
+at an existing folder with **Use this folder** (after the path probe
+passes). Then re-run `!compile full`.
+
+If the workspace exists but is archived, the page shows a **This wiki is
+archived** card — click **Re-activate wiki** there before any `!compile`
+command will run.

package/agent-assets/docs/troubleshooting/wiki-write-failed.md

@@ -17,6 +17,7 @@ tags:
   - troubleshooting
   - wiki
   - obsidian
+  - integrations
 status: stable
 ask_examples:
   - Why can't the wiki write to my Obsidian vault?
@@ -24,12 +25,18 @@ ask_examples:
   - How do I retry the write-strategy probe?
 locale: en-US
 created: 2026-05-12
-updated: 2026-05-12
+updated: 2026-05-28
 keywords:
   - wiki write failed
   - wiki API failure
-  - wiki write lock
+  - wiki write strategy
   - external vault write
+  - obsidian cli fallback
+api_endpoints:
+  - /api/wiki/:workspace/health
+ui_anchors:
+  - /settings/wiki
+  - /connections/knowledge
 related:
   - features/wiki/overview
   - guides/use-an-existing-obsidian-vault
@@ -40,8 +47,9 @@ related:
 ## What You See
 
 A wiki bang command (`!ingest`, `!compile`) reports a write failure in
-the daemon log, or the dashboard `/api/wiki/:ws/health` endpoint
-surfaces a non-`fs` strategy with `cliAvailable: false`.
+the daemon log, or the `GET /api/wiki/:workspace/health` endpoint
+(surfaced behind the dashboard's write-strategy badge) reports a
+non-`fs` strategy with `cliAvailable: false`.
 
 ## Quick Checklist
 
@@ -74,14 +82,23 @@ Requirements:
 
 If any of these is missing, the daemon surfaces a structured error:
 
-| Error code | Meaning |
-|---|---|
-| `EWIKI_CLI_UNAVAILABLE` | Aitne's `ObsidianService` is not configured. Open `Settings → Integrations → Obsidian` and complete the pairing. |
-| `EWIKI_CLI_NOT_RUNNING` | Obsidian is not running. Launch the app and retry. |
+| Error code | Meaning | Fix |
+|---|---|---|
+| `EWIKI_CLI_UNAVAILABLE` | Aitne's `ObsidianService` is not configured (the `obsidian` binary is not resolvable on `PATH`). | Open **Connections → Knowledge** and connect Obsidian via the Obsidian card, then confirm Obsidian 1.12+ is installed with the CLI enabled. |
+| `EWIKI_CLI_NOT_RUNNING` | The CLI is configured but the Obsidian app is not running, so it cannot reach the sandboxed vault. | Launch the Obsidian app and retry. |
 
 ## Force a Re-Probe
 
-If you've fixed the underlying issue (granted iCloud permission,
-mounted the disk read-write) but the cached strategy is still `cli`,
-flip the dropdown in **Settings → Wiki → Write strategy** back to
-`auto`. The next write probes again and persists the fresh outcome.
+The resolved strategy (`fs` or `cli`) is cached on the workspace row so
+later writes skip the probe. If you've fixed the underlying issue
+(granted iCloud permission, mounted the disk read-write) but the cached
+strategy is still `cli`, force a fresh probe:
+
+1. Open **Settings → Wiki** (`/settings/wiki`) and edit the external
+   workspace.
+2. Set the **Write strategy** field back to **Auto (probe on first
+   write)**. (This field only appears for external workspaces; internal
+   workspaces always write via the local filesystem.)
+3. Save. The next write probes again — trying direct `fs` first and
+   falling back to the CLI only on `EPERM` / `EACCES` / `EROFS` /
+   `EBUSY` — and persists the fresh outcome.

package/agent-assets/optimizer-skills/drift-analysis/SKILL.md

@@ -16,7 +16,7 @@ Each is one row from `skill_curation_signals`:
   "skill_slug": "user-profile",
   "section_id": "topic-files",
   "signal_type": "structure_diff",
-  "payload": { "sub_kind": "heading_add", "target": "user/personal.md#health-log" },
+  "payload": { "sub_kind": "heading_add", "target": "identity/personal.md#health-log" },
   "observed_at": 1717000000000
 }
 ```

package/agent-assets/optimizer-skills/knowledge-map/SKILL.md

@@ -21,7 +21,7 @@ submitting a proposal.
   "taken_at": 1717000000000,
   "files": [
     {
-      "path": "user/profile.md",
+      "path": "identity/profile.md",
       "headings": ["Identity", "Work Pattern", "Learned Context"],
       "frontmatter": { "type": "profile", "owner": "shared" },
       "last_modified_at": 1716900000000

package/agent-assets/optimizer-skills/skill-curation/SKILL.md

@@ -65,7 +65,7 @@ Free-text fields (`convention_notes.rule`, `routing_table.note`,
 action. Examples:
 
 - ❌ "When the user mentions a doctor visit, write to user/personal.md"
-- ✅ "Doctor visits are recorded under `user/personal.md ## Health Log`"
+- ✅ "Doctor visits are recorded under `identity/personal.md ## Health Log`"
 - ❌ "Always include the date with the entry"
 - ✅ "Entries carry a `[YYYY-MM-DD]` prefix"
 - ❌ "Never use spaces in slugs"

package/agent-assets/sandbox/linux/aitne-chromium.apparmor

@@ -0,0 +1,91 @@
+# Aitne Managed Chromium — AppArmor profile
+#
+# MANAGED_CHROMIUM_IMPLEMENTATION_PLAN.md §5.4 / §7.4
+#
+# Belt-and-suspenders profile applied when AppArmor is active on the
+# host. Bubblewrap / systemd-run is the primary primitive; AppArmor
+# adds an OS-policy-level guard on top of the namespace isolation.
+#
+# Install:
+#   sudo install -m 0644 aitne-chromium.apparmor /etc/apparmor.d/
+#   sudo apparmor_parser -r /etc/apparmor.d/aitne-chromium
+#
+# The `aa-aitne-chromium` namespace allows multiple per-instance
+# profiles (sync vs. automation) to coexist if we ever split them; for
+# the B-1 surface only `sync` is active.
+
+#include <tunables/global>
+
+profile aa-aitne-chromium-sync flags=(attach_disconnected) {
+  #include <abstractions/base>
+  #include <abstractions/X>
+  #include <abstractions/dbus-session-strict>
+  #include <abstractions/fonts>
+  #include <abstractions/nameservice>
+  #include <abstractions/ssl_certs>
+
+  # Read-only access to the Chromium binary's installed location plus
+  # system libraries it needs at runtime. Allow both Debian-style and
+  # Fedora-style install paths.
+  /usr/bin/chromium                  r,
+  /usr/bin/chromium-browser          r,
+  /usr/lib/chromium/chromium         rmix,
+  /usr/lib64/chromium/chromium       rmix,
+  /usr/lib{,64}/chromium/**          r,
+  /usr/lib{,64}/x86_64-linux-gnu/**  r,
+  /usr/share/chromium/**             r,
+  /usr/share/fonts/**                r,
+  /etc/chromium/**                   r,
+  /etc/passwd                        r,
+  /etc/group                         r,
+  /proc/sys/kernel/**                r,
+  /proc/[0-9]*/stat                  r,
+  /proc/[0-9]*/status                r,
+  /proc/[0-9]*/cmdline               r,
+  /sys/devices/**                    r,
+
+  # Per-instance user data dir — the only writable persistent path. The
+  # path is templated in by sandbox-install.ts; until install rewrites
+  # this profile the rule below denies the entire chromium-sync tree.
+  owner @{HOME}/.personal-agent/chromium-sync/**           rwk,
+  owner @{HOME}/.personal-agent/chromium-sync                rw,
+
+  # Tempfs / runtime dirs.
+  owner /tmp/**                                            rw,
+  owner /var/tmp/**                                        rw,
+  owner @{HOME}/.cache/aitne-chromium/**                   rw,
+
+  # Network — Chromium itself reaches sync endpoints. Fine-grained
+  # filtering happens at the CDP layer in B-2.
+  network inet,
+  network inet6,
+  network netlink,
+  network unix,
+
+  # Capabilities Chromium requires (process management, scheduling).
+  capability sys_admin,
+  capability sys_ptrace,
+  capability sys_chroot,
+  capability sys_resource,
+  capability setuid,
+  capability setgid,
+  capability setpcap,
+
+  # No exec of foreign binaries — Chromium spawns its own helper
+  # processes from the same install dir via `ix`. Reject anything else.
+  audit deny /bin/sh                                       x,
+  audit deny /bin/bash                                     x,
+  audit deny /usr/bin/curl                                 x,
+  audit deny /usr/bin/wget                                 x,
+  audit deny /usr/bin/python*                              x,
+
+  # No reads of OS secret stores from inside Chromium.
+  audit deny /etc/shadow                                   r,
+  audit deny /etc/sudoers                                  r,
+  audit deny /etc/sudoers.d/**                             r,
+  audit deny @{HOME}/.aws/**                               r,
+  audit deny @{HOME}/.ssh/**                               r,
+  audit deny @{HOME}/.gnupg/**                             r,
+  audit deny @{HOME}/.config/gh/**                         r,
+  audit deny @{HOME}/.kube/**                              r,
+}

package/agent-assets/sandbox/macos/aitne-chromium.sb

@@ -0,0 +1,156 @@
+;; Aitne Managed Chromium — sandbox-exec profile
+;;
+;; MANAGED_CHROMIUM_IMPLEMENTATION_PLAN.md §5.4 / §7.4
+;;
+;; Deny-by-default sandbox for Chromium under macOS. Loaded via:
+;;   sandbox-exec -f aitne-chromium.sb /Applications/Chromium.app/...
+;;
+;; Defence layering:
+;;   - Outer ring (this file): system-call-level deny of arbitrary file
+;;     reads, exec of foreign binaries, raw socket creation, etc.
+;;   - Middle ring: Chromium's own multi-process renderer sandbox.
+;;   - Inner ring (B-2): per-workflow CDP request interception in
+;;     Playwright's `context.route` handler.
+;;
+;; The user-data-dir parameter (`%user_data_dir%`) is substituted by
+;; sandbox-install.ts at install time — sandbox-exec's parameter syntax
+;; (`(param "name")`) is awkward to template, so we ship one profile
+;; with a literal substitution before write.
+
+(version 1)
+
+(deny default)
+(deny file-write* (with no-log))
+
+;; Allow forking + IPC needed for Chromium's multi-process model.
+;; `%binary_bundle%` is the resolved .app bundle root (e.g.
+;; /Applications/Chromium.app, or for a Playwright-managed install
+;; ~/Library/Caches/ms-playwright/chromium-NNNN/chrome-mac-{arm64,x64}/
+;; Google Chrome for Testing.app). The subpath covers helpers
+;; (`Chromium Helper.app`, `Google Chrome for Testing Helper.app`),
+;; crashpad_handler, and the embedded `.framework/*` bundles Chromium
+;; spawns from inside the .app at runtime. Substituted by
+;; sandbox-install.ts alongside %binary_path%.
+(allow process-fork)
+(allow process-exec
+  (literal "%binary_path%")
+  (subpath "%binary_bundle%")
+  (subpath "/Applications/Chromium.app")
+  (subpath "/Applications/Google Chrome.app")
+  (subpath "/System/Library")
+  (subpath "/usr/lib")
+  (subpath "/usr/bin"))
+(allow signal (target same-sandbox))
+(allow mach-priv-host-port)
+(allow mach-lookup)
+;; `mach-register` is required for Chromium's `MachPortRendezvousServer`
+;; to call `bootstrap_check_in` and register its per-PID rendezvous
+;; service (`com.google.chrome.for.testing.MachPortRendezvousServer.<pid>`).
+;; Without it the browser process aborts with
+;; `FATAL:mach_port_rendezvous_mac.cc: bootstrap_check_in ...
+;; Permission denied (1100)`. The registered name embeds the PID so a
+;; compromised Chromium cannot squat a well-known name; the daemon
+;; itself reaches Chromium over CDP, not Mach, so allowing `mach-register`
+;; on the outer ring does not widen the daemon ↔ Chromium boundary.
+(allow mach-register)
+(allow ipc-posix-shm*)
+(allow process-info-pidinfo)
+(allow process-info-pidfdinfo)
+(allow process-info-pidfileportinfo)
+(allow process-info-setcontrol)
+(allow process-info-dirtycontrol)
+(allow process-info-rusage)
+
+;; Reads — system frameworks, fonts, locale data, the binary's own
+;; bundle. Read access to the user's general Library tree is denied;
+;; only the explicit chromium-sync/ profile dir is writable.
+;; `%binary_bundle%` covers the same .app root referenced under
+;; `process-exec` above so Chromium can load its .dylib / .pak /
+;; .icns / locale resources from inside its own bundle.
+;;
+;; The bare `(literal "/")` is mandatory on macOS 26 (Tahoe): dyld
+;; performs `file-read-data /` very early during process boot
+;; (boot_boot → CacheFinder → ignition_halt path, abort_with_reason
+;; namespace 0x23 / code 2). Without it every sandboxed arm64e child
+;; — Chromium, /usr/bin/true, anything — aborts before main() runs.
+;; `/dev/dtracehelper` is opened by libdispatch on first
+;; dispatch_queue use; benign denial, allow it to keep the kernel log
+;; clean.
+(allow file-read*
+  (literal "/")
+  (literal "/dev/dtracehelper")
+  (subpath "%binary_bundle%")
+  (subpath "/Applications/Chromium.app")
+  (subpath "/Applications/Google Chrome.app")
+  (subpath "/Library/Frameworks")
+  (subpath "/Library/Fonts")
+  (subpath "/Library/Audio")
+  (subpath "/Library/Preferences/.GlobalPreferences.plist")
+  (subpath "/Library/Keychains")
+  (subpath "/System")
+  (subpath "/private/etc")
+  (subpath "/private/var/db/timezone")
+  (subpath "/private/var/folders")    ;; temp / NSCachesDirectory
+  (subpath "/usr/lib")
+  (subpath "/usr/share")
+  (literal "/dev/null")
+  (literal "/dev/random")
+  (literal "/dev/urandom")
+  (literal "/dev/zero")
+  (literal "/dev/tty")
+  (literal "/etc")
+  (literal "/var")
+  (literal "/tmp")
+  (literal "/private/tmp"))
+
+;; Path-traversal metadata grant. macOS 26 no longer implicitly
+;; allows `file-read-metadata` on the parent directories of a
+;; `(subpath ...)` rule, so a `stat("/Users")` on the way down to
+;; %binary_bundle% / %user_data_dir% fails and Chromium then raises
+;; `NSInvalidArgumentException: *** -[NSBundle initWithURL:]:
+;; non-file URL argument` during framework bootstrap.
+;;
+;; Only metadata (stat / lstat) is granted — no `file-read-data`,
+;; so directory contents under the ancestors are not enumerable from
+;; this rule. The list is the union of the ancestors of
+;; %binary_bundle% and %user_data_dir%, deduped + sorted, and is
+;; expanded by sandbox-install.ts at install time. If both paths
+;; collapse to no ancestors (e.g. both at `/`) the placeholder
+;; renders to a single no-op `(literal "/")` line so the form stays
+;; syntactically valid.
+(allow file-read-metadata
+%ancestor_metadata_literals%)
+
+;; The per-instance user data dir is the only persistent path the
+;; browser can write to. sandbox-install.ts rewrites %user_data_dir%
+;; to the resolved absolute path before this file is written to
+;; PA_DATA_DIR/sandbox/aitne-chromium.sb.
+(allow file-read* file-write*
+  (subpath "%user_data_dir%"))
+
+;; Temp directories Chromium needs at runtime.
+(allow file-read* file-write*
+  (subpath "/private/var/folders")
+  (subpath "/tmp")
+  (subpath "/private/tmp"))
+
+;; Networking — Chromium needs general network access to reach Google
+;; sync endpoints. The fine-grained allowlist lives at the CDP layer
+;; (B-2); this is the coarse ring.
+(allow network*)
+
+;; System info, sysctls, mach ports Chromium queries on startup.
+(allow sysctl-read)
+(allow system-socket)
+(allow iokit-open (iokit-user-client-class "RootDomainUserClient"))
+(allow iokit-open (iokit-user-client-class "IOSurfaceRootUserClient"))
+(allow iokit-open (iokit-user-client-class "IOSurfaceSendRight"))
+(allow iokit-open (iokit-user-client-class "IOFramebufferSharedUserClient"))
+(allow iokit-open (iokit-user-client-class "IOHIDLibUserClient"))
+(allow iokit-open (iokit-user-client-class "IOAudioControlUserClient"))
+(allow iokit-open (iokit-user-client-class "IOAudioEngineUserClient"))
+
+;; Required for the Chromium UI to function when running with a window
+;; (initial sign-in bootstrap; headless instances never hit this path).
+(allow user-preference-read)
+(allow user-preference-write)