AkurAI-Build

Latest change e11509261b6a2aa4ea9ef67250b0be01bfb4f53b - Restore paths swept in from uncommitted WIP by Ólafur Búi Ólafsson

---
name: self-healing-and-skill-propagation
description: "Close issues to done/blocked, interpret CI waiting status, rerun failed tasks, and share agent-built CLI tools as skills"
---

# Self-Healing and Skill Propagation

## Closing the loop on your own work
An agent task ends in `done` or `blocked` — never resting in `in_review`. After posting evidence and requesting peer review, run the literal command yourself:

    multica issue status <ISSUE-KEY> done --output json
    multica issue status <ISSUE-KEY> blocked --output json   # with a comment stating the dated unblock condition

If your work needs a reviewer, @-mention them in a comment, then still move the issue to `done` once review evidence lands, or `blocked` naming the reviewer as the dependency. Parking in `in_review` at the end of a run is a defect.

## Interpreting AkurAI Build run status
A run with `status: waiting` is NOT stalled or failed. Read the jobs before concluding anything:

    akurai_run_show {"id": <run-id>}

- `verify`/`package` jobs `succeeded` + a `deploy` job with `approval_required: true` and `status: waiting` = success pending human promotion. Report it as passing; do not retry, do not open a failure issue.
- Only open a CI failure issue when a job shows `status: failed` with a non-zero `exit_code`, and quote the log excerpt.
- Before filing, check whether a later retry of the same commit already passed (`akurai_runs` filtered by repository); dedupe against open issues by searching `multica issue search <repo or error text>`.

## Self-healing failed agent tasks
When you observe another issue whose latest execution failed with `failure_reason` `agent_error.process_failure` or `cancelled` (daemon restart), and the issue is still `todo`/`in_progress` with no live task:

    multica issue rerun <ISSUE-KEY> --output json

Rerun at most once per observation pass. If the rerun fails the same way, set the issue `blocked` with the exact `error` string in a comment so a human sees it.

## Propagating tools you build
When you create a reusable CLI helper or script during a task:
1. Commit it to the owning repository under `scripts/` (or its own repo if cross-cutting), with a usage header comment. Never leave it only in a workspace or `.tmp/`.
2. Author a workspace skill documenting invocation, inputs, and failure modes:

       multica skill create --name <tool-name> --content-file <path> --output json

3. Bind it to every agent so the whole office can use it:

       multica agent list --output json | jq -r '.[].id' | while read -r id; do multica agent skills add "$id" --skill-ids <skill-id> --output json >/dev/null || exit 1; done

4. Reference the skill from the repository's tracked guidance (`AGENTS.md`) in the same commit.
Prefer improving an existing skill over creating a near-duplicate; search first with `multica skill list --output json | jq -r '.[].name'`.


## Skill source of truth
Multica workspace skills (`multica skill list/get`) are the canonical skill source, delivered to you as bound skills and via the daemon-materialized `.pi/skills/` in your task worktree. Never hand-read skill files from arbitrary filesystem paths or other repos' `.pi/` directories; if a skill seems missing, check your bindings (`multica agent skills list <your-agent-id>`) rather than scavenging the filesystem.

## Probes vs durable knowledge
A direct shell command you run is a probe: it answers one question once. Any procedure you had to discover by probing — a command sequence, a failure signature, a service quirk — must be written down the same run: repository facts into that repo's tracked `AGENTS.md`, cross-repository procedure into a Multica workspace skill (create or update, bind broadly). If you fixed something by hand, the fix is not done until the skill or guidance that prevents the rediscovery is committed.


## Known CI failure signatures
- `cargo: command not found` in verify → worker toolchain PATH issue; check `akurai_workers`, then a retry after the toolchain fix.
- Local path dependency fails to resolve at `.../workspaces/AkurAI-Framework/...` or `.../workspaces/akurai-log/...` → the shared framework checkout on the Titan worker is stale. Fix: `ssh titan 'cd ~/.local/share/akurai-build/workspaces/<Repo> && git fetch origin && git reset --hard origin/<default-branch>'`, then `akurai_run_retry` the failed run.
- `cargo fmt --check` diff in verify → check whether a newer run on the same repo already passes before hand-fixing; the diff in the failing run's log is the exact patch if not.

- Runs list clogged with `waiting` entries → most are superseded approval-gated deploys. Keep only the newest waiting run per repository (verify/package succeeded, deploy awaiting approval); cancel the rest with `akurai_run_cancel {"id": N}`. Never promote production deploys as part of cleanup.


## CI worker sandbox (Titan) — writable home is required
- `akurai-build.service` hardening must include the drop-in
  `/etc/systemd/system/akurai-build.service.d/writable-home.conf`
  (`ProtectHome=false`, `ReadWritePaths=/home/olibuijr`). Without it, native
  jobs fail with `Read-only file system` on `~/.cargo/registry` or
  `~/.local/bin` — that signature means the drop-in is missing, not a repo bug.
- Service binary/config stay `ReadOnlyPaths`; the host deploy agent remains the
  only path that swaps the service binary.

## Workspace hygiene
- Successful runs self-delete their workspace. `Runner::prune_stale_workspaces`
  (hourly, idle worker loop, since commit ce4b48c) reaps terminal-run
  workspaces older than 7 days and orphans. Non-numeric `workspaces/` entries
  are shared checkouts — never delete them.
- If disk fills before the hourly prune catches up: keep non-terminal
  (queued/running/waiting) run IDs from `akurai_runs`, delete other numeric
  workspace dirs.