Multica Runtimes And Repos

Multica Runtimes and Repos

Quick start

For "agent did not run" or "repo checkout failed", read the chain before changing anything:

multica agent get <agent-id> --output json
multica runtime list --output json
multica repo checkout <repo-url>

Runtime and repo commands affect active agent execution. Do not restart daemons, update runtimes, or check out arbitrary repos just to test.

Core model

A runtime is the execution target behind an agent. A daemon owns local runtime processes and claims queued tasks from the server.

The chain is:

1. user action creates or updates an agent_task_queue row; 2. the task points at an agent and runtime; 3. server wakes the runtime over daemon websocket when possible; 4. daemon polls/claims the task; 5. server returns task context, repos, project resources, prior session/workdir hints, and task token; 6. daemon prepares a workdir and launches the provider CLI; 7. multica repo checkout talks to the local daemon, not directly to GitHub.

CLI

multica runtime list --output json
multica runtime usage <runtime-id> --output json
multica runtime activity <runtime-id> --output json
multica runtime update <runtime-id> --target-version <version> --output json
multica runtime delete <runtime-id>
multica repo checkout <url>
multica repo checkout <url> --ref <branch-or-sha>

runtime update and runtime delete are writes. runtime delete removes a runtime registration; if active agents are still bound, it refuses unless the user explicitly passes --cascade, which archives those agents and cancels their queued/running tasks before deleting the runtime. repo checkout creates a git worktree in the task working directory.

repo checkout requires MULTICA_DAEMON_PORT; it is intended to run inside a daemon task. If absent, you are not in the normal agent checkout path.

Debugging an agent that did not run

Check in this order:

1. Was a task supposed to be created? Inspect issue/comment/autopilot context. 2. Is the assignee an agent or squad? A squad routes to its leader. 3. Is the agent archived or bound to a runtime the actor cannot use? 4. Is the runtime online? multica runtime list --output json. 5. Did the daemon heartbeat recently? Runtime last_seen_at is the visible clue. 6. Did the task get claimed or is it stuck pending/running/waiting for local directory? 7. If repo checkout failed, classify it after checking whether repo context was present in the task/project context.

Repos

The runtime brief lists repos available to this task. Treat that list as the authority for agent checkout unless the user explicitly asks to bind a new project resource.

Workspace repos and project resources are not the same thing:

• workspace repo metadata can appear in workspace context;
• github_repo project resources are durable project context and can affect future tasks;
• local_directory resources point at a path owned by a daemon and carry local-machine assumptions.

Do not add a project resource just because repo checkout failed. First determine whether the user asked for durable project context or just a task checkout.

More source-backed details: references/runtimes-and-repos-source-map.md.

Runtimes and repos source map

• server/cmd/multica/cmd_runtime.go registers runtime list, usage, activity, update, and delete.
• runtime list reads /api/runtimes and prints id, name, runtime_mode, provider, status, and last_seen_at.
• runtime update posts to /api/runtimes/{runtime-id}/update; with --wait it polls update status.
• runtime delete deletes /api/runtimes/{runtime-id}; with --cascade, it first reads the runtime_has_active_agents conflict payload and posts those ids to /api/runtimes/{runtime-id}/archive-agents-and-delete.
• server/cmd/multica/cmd_repo.go registers repo checkout <url> [--ref].
• repo checkout requires MULTICA_DAEMON_PORT, sends workspace_id, workdir, ref, agent_name, and task_id to local daemon /repo/checkout, then prints the checked-out path.
• server/cmd/server/router.go registers daemon APIs under /api/daemon, including workspace repos and task claim.
• server/internal/daemon/daemon.go claims tasks, prepares workdirs, launches provider CLIs, and reports completion.
• server/internal/daemon/execenv/runtime_config.go injects task/project/repo context into agent workdirs.