Skip to content

150. Separate execution workspace from optional target repository ​

Date: 2026-10-21

Status ​

Accepted

Builds on ADR 0093, which already separates a status destination from a code repository. It also amends ADR 0098, and complements ADR 0133 and ADR 0141: a missing target repository does not remove entity attribution or content-filtering requirements.

Context ​

fullsend run currently requires a local target directory: the CLI declares --target-repo and marks it required in internal/cli/run.go at 5e05c5487. Some Jira, tenant, and service-level tasks have configuration and input but no target code repository. The CLI also auto-detects a forge from CI environment variables when --forge is omitted (detectForgePlatform in run.go at 5e05c5487), which is execution-host metadata, not proof that the host checkout is the target. Treating that checkout as a target would conflate configuration, execution, code, status, and credential scope.

The runner therefore needs a repository-less contract that works for direct invocations and CI-hosted runs, while keeping repository-targeted callers compatible. The decision supports later managed execution without making that execution path part of this change. See agent-infrastructure.md and agent-architecture.md for the broader problems.

Options ​

Infer repository-less mode when no path is supplied ​

Rejected. An omitted path may be an operator or workflow error, so the caller must choose repository-targeted or repository-less mode explicitly.

Represent the scratch directory as a target repository ​

Rejected. A scratch directory must not acquire Git, repository identity, target instructions, repository-scoped credentials, or target status semantics merely because a runtime needs a working directory.

Use the CI host checkout as the default target ​

Rejected. The workflow project is an execution host unless the caller explicitly selects it as the target.

Add a separate runner for repository-less execution ​

Rejected. A separate runner would duplicate the existing runAgent orchestration: the entrypoint loads run configuration and starts harness resolution (runAgent at 5e05c5487), then composes and resolves the harness (runAgent at the same commit). Those responsibilities should remain shared while target-specific behavior becomes explicit.

Decision ​

fullsend run requires exactly one of:

  • --target-repo PATH for a local target directory; or
  • --no-target-repo for repository-less execution.

The runner distinguishes three runtime concepts:

  • Sandbox workspace root is the existing WorkspaceDir() runtime API, backed by sandbox.SandboxWorkspace (/sandbox/workspace). Its meaning remains unchanged: it is the root for runner-managed files and output (see runtime.Runtime.WorkspaceDir, ClaudeRuntime.WorkspaceDir, and sandbox.SandboxWorkspace at 5e05c5487).
  • Execution directory is a runner-owned directory that is always present for the agent process. A repository-targeted run may colocate it with the target checkout; a repository-less run uses an empty scratch directory beneath the sandbox workspace root. It is distinct from RunParams.RepoDir, which retains its existing meaning as the target repository path and is empty when no target repository exists. RunParams.RepoDir is the runtime's target-repository path, and the current Codex configuration renderer rejects an empty value (RunParams and renderCodexConfig at 5e05c5487, same commit). The implementation must pass the execution directory separately to the runtime rather than redefining RepoDir.
  • Target repository is optional target identity and content. It is absent in repository-less mode even though the execution directory is present.

Repository-less mode does not create or upload a target checkout, and it does not assign target-repository semantics to the scratch execution directory. In particular, TARGET_REPO_DIR, FULLSEND_TARGET_REPO_DIR, and REPO_DIR are absent in this mode.

Harness compatibility is explicit. target_repo_required is a top-level scalar resolved through base composition only; a child harness may set it to false to override an inherited true. It is not settable in legacy forge: blocks or overlays:. After base composition and resolution of the other overlay fields, the effective value defaults to true when absent, preserving existing behavior. A malformed value is a load-time validation error. Fullsend applies the compatibility gate immediately after harness resolution and capability validation, before environment validation or target-dependent environment expansion, credential selection, script execution, or sandbox creation. Only an effective value of false may opt into --no-target-repo; any other effective value keeps the run target-required. Repository-dependent harnesses do not receive a fabricated target.

--fullsend-dir remains the source of harness, agent, skill, and policy configuration: runAgent resolves it as the workspace root and uses it to load configuration and resolve the harness (runAgent at 5e05c5487, harness.ComposeOpts and harness resolution at the same commit). It is independent of the execution directory and target repository. In repository-less mode, no forge is selected unless the caller explicitly supplies --forge (or an equivalent explicit configuration). CI variables may identify the execution environment for diagnostics, but they never select the forge, target identity, repository credential scope, or status destination. An explicit forge selects an integration adapter only; external repository access and external status or output destinations still require explicit resource and destination data. Inference credentials remain usable when otherwise authorized; they are not repository credentials. A runner-local output directory may retain a safe default.

Status routing continues to follow ADR 0093. This ADR amends ADR 0098's attribution rule: entity-first attribution records the target repository as absent for repository-less runs, while retaining the verified invocation identity, effective policy, harness revision, and resolved entity. Run, cache, and entity identity must not use a sentinel repository in its place. ADR 0141 applies when a repository-less run has a handled entity requiring an entity-context snapshot; it does not require a target checkout and does not define execution for runs without such an entity. Entity content remains subject to ADR 0133; for supported Git-forge entities, snapshot content also follows ADR 0141.

The implementation must satisfy these repository-less acceptance criteria:

  • preserve existing repository-targeted CLI and workflow behavior;
  • make --no-target-repo explicit and mutually exclusive with --target-repo;
  • load harness, agent, skill, and policy configuration from --fullsend-dir, independently of the target repository;
  • use a scratch execution directory without copying the CI host checkout or injecting its target instructions, and fail clearly when a selected harness requires a repository;
  • keep host metadata, task or event source, target context, status/output destination, and credential scope distinct;
  • fail early with an actionable diagnostic when a non-existent --target-repo path resembles an owner/repo identifier;
  • demonstrate direct runs and repository-less runs from both GitHub Actions and GitLab CI.

Forge scope ​

The runtime contract is forge-neutral and applies to GitHub, GitLab, and Forgejo: repository-less mode never selects a target from CI host metadata, and a target is supplied only explicitly. This ADR does not add or change forge-specific adapters, workflows, credentials, or status routing. GitHub Actions and GitLab CI are the required demonstrations; Forgejo-specific workflow integration is outside this ADR because no Forgejo adapter or workflow is changed here.

Consequences ​

  • Repository-independent agents get a stable runtime contract without weakening repository-targeted execution.
  • Existing and unannotated harnesses remain target-repository–required, while repository-less compatibility becomes an explicit, reviewable capability.
  • Runtime adapters must distinguish a working directory from target-repo identity, which may require small interface and environment changes.
  • CI hosts can provide configuration and execution without implicitly granting target-repository authority or repository-scoped credentials.
  • Managed polling, OpenShift Jobs, tenant schema changes, and making every built-in agent repository-independent remain follow-up work.

References ​