@jr2/cli 0.2.1 → 0.4.1

package/README.md

@@ -1,6 +1,6 @@
 # @jr2/cli
 
-The `jr2` binary: the interface to a jr2 [Instance](https://github.com/snapwich/jr2/blob/main/CONTEXT.md) — a folder of
+The `jr2` binary: the interface to a jr2 [Instance](https://github.com/snapwich/jr2/blob/main/GLOSSARY.md) — a folder of
 workflows deployed to whatever cluster the current `kubectl` context names.
 
 ```sh

package/bin/jr2.js

@@ -5,9 +5,9 @@
 // loader to erase types the same way Node would, then hands over to the `.ts` sources.
 //
 // One entry for both worlds, deliberately: a checkout-only `.ts` bin plus an installed-only `.js`
-// bin would mean the binary users run is not the binary the checkout's tiers run. The image
-// bundle solves the same problem with `tsx` (see INSTANCE_DOCKERFILE) because there the entry is
-// the orchestrator's, not this one.
+// bin would mean the binary users run is not the binary the checkout's tiers run. The
+// Orchestrator Kit image solves the same problem with `tsx` (see deploy/orchestrator/Dockerfile)
+// because there the entry is the orchestrator's, not this one.
 //
 // After the hook, the launcher's one decision (ADR-0056): inside an Instance that resolves its own
 // `@jr2/cli` to a different copy, hand off — run THAT copy's binary with the same argv and stdio

package/manifests/operator.yaml

@@ -516,6 +516,36 @@ spec:
                   of ADR-0005. Unset leaves volume ownership to the images' own uids.
                 format: int64
                 type: integer
+              gitCredentials:
+                description: |-
+                  GitCredentials are the push Secrets of the `git.credentials` entries
+                  this Sandbox's pushes spend (ADR-0051, ADR-0068): one per entry the
+                  Orchestrator matched to a pushed Repo Slot's url at provision, named
+                  as a Repo's secretRef names its Secret. The operator projects each
+                  into the sidecar named "effector" — the Sandbox Effector — beside its
+                  secrets, at `@git/<name>/` in the projected volume that container
+                  mounts at /run/jr2/secrets, one file per key jr2 writes there
+                  (`entry.json`, `username`, `password`, `identity`, `identity.pub`,
+                  `known_hosts`, `sign.identity`, `sign.private.asc`), each when the
+                  Secret holds it. No other container gets it. The operator reads no
+                  Secret: the kubelet projects it.
+                items:
+                  description: |-
+                    SandboxGitCredential names one entry's push Secret, in the Sandbox's
+                    namespace.
+                  properties:
+                    name:
+                      description: Name is the Secret's name.
+                      maxLength: 63
+                      pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
+                      type: string
+                  required:
+                  - name
+                  type: object
+                type: array
+                x-kubernetes-list-map-keys:
+                - name
+                x-kubernetes-list-type: map
               idleTimeout:
                 description: |-
                   IdleTimeout garbage-collects the Sandbox after this duration with no
@@ -532,8 +562,8 @@ spec:
                   Scheduled verbatim — the operator adds nothing to them, not even the
                   hardened securityContext default it gives sidecars, because an init step
                   is composed by whoever built the spec and it must be able to say exactly
-                  what it needs. This is how jr2's runtime reaches a Sandbox (ADR-0037): one
-                  step populates an /opt/jr2 volume, a second proves the primary image on it.
+                  what it needs. This is how jr2 proves a Sandbox's image (ADR-0037): one
+                  step runs the primary image with the /opt/jr2 image volume mounted.
                 items:
                   description: A single application container that you want to run
                     within a pod.
@@ -2064,6 +2094,70 @@ spec:
                   it; its own soft affinity toward nodes holding this Sandbox's Repo caches
                   sits beside it, and a preference never conflicts with a requirement.
                 type: object
+              podResources:
+                description: |-
+                  PodResources is the pod-level ceiling (KEP-2837's `spec.resources` on
+                  the Pod): the whole Size, cpu and memory, requests = limits (ADR-0060).
+                  It is what lets a container with no limit of its own — a User Container
+                  the Machine gave no split — share the pod's budget, and it holds the pod
+                  Guaranteed. Copied verbatim; unset leaves the Pod without one.
+                properties:
+                  claims:
+                    description: |-
+                      Claims lists the names of resources, defined in spec.resourceClaims,
+                      that are used by this container.
+
+                      This field depends on the
+                      DynamicResourceAllocation feature gate.
+
+                      This field is immutable. It can only be set for containers.
+                    items:
+                      description: ResourceClaim references one entry in PodSpec.ResourceClaims.
+                      properties:
+                        name:
+                          description: |-
+                            Name must match the name of one entry in pod.spec.resourceClaims of
+                            the Pod where this field is used. It makes that resource available
+                            inside a container.
+                          type: string
+                        request:
+                          description: |-
+                            Request is the name chosen for a request in the referenced claim.
+                            If empty, everything from the claim is made available, otherwise
+                            only the result of this request.
+                          type: string
+                      required:
+                      - name
+                      type: object
+                    type: array
+                    x-kubernetes-list-map-keys:
+                    - name
+                    x-kubernetes-list-type: map
+                  limits:
+                    additionalProperties:
+                      anyOf:
+                      - type: integer
+                      - type: string
+                      pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
+                      x-kubernetes-int-or-string: true
+                    description: |-
+                      Limits describes the maximum amount of compute resources allowed.
+                      More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
+                    type: object
+                  requests:
+                    additionalProperties:
+                      anyOf:
+                      - type: integer
+                      - type: string
+                      pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
+                      x-kubernetes-int-or-string: true
+                    description: |-
+                      Requests describes the minimum amount of compute resources required.
+                      If Requests is omitted for a container, it defaults to Limits if that is explicitly specified,
+                      otherwise to an implementation-defined value. Requests cannot exceed Limits.
+                      More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
+                    type: object
+                type: object
               port:
                 default: 8080
                 description: |-
@@ -2073,6 +2167,12 @@ spec:
                 maximum: 65535
                 minimum: 1
                 type: integer
+              priorityClassName:
+                description: |-
+                  PriorityClassName is the Pod's priority class, copied verbatim
+                  (ADR-0060): the Instance's sandbox class, `jr2-sandbox` unless the
+                  cluster names its own. Empty leaves the cluster's default.
+                type: string
               readinessProbe:
                 description: |-
                   ReadinessProbe overrides the primary container's readiness probe. When
@@ -2237,8 +2337,8 @@ spec:
                   needs it mounts the same volume by name. Scheduling prefers nodes whose
                   `Repo` status reports the key present; `Ready` waits for every key to be
                   present on the pod's node and fetched since this Sandbox was created.
-                  This is the whole of what the CRD knows about git: clone and worktree
-                  stay the Orchestrator's post-Ready step (ADR-0004).
+                  With gitCredentials, this is the whole of what the CRD knows about git:
+                  clone and worktree stay the Orchestrator's post-Ready step (ADR-0004).
                 items:
                   description: SandboxRepo names one Repo a Sandbox attaches.
                   properties:
@@ -2265,7 +2365,15 @@ spec:
                 - key
                 x-kubernetes-list-type: map
               resources:
-                description: Resources are the compute resources for the primary container.
+                description: |-
+                  Resources are the primary container's resources — the Harness's share
+                  of the Workspace's Size (ADR-0060), copied onto the container verbatim.
+                  The Orchestrator splits the Size and sets requests = limits for cpu and
+                  memory, plus the `/work` disk as an ephemeral-storage request with no
+                  limit (a limit would evict the pod and lose `/work`). The operator
+                  computes nothing here: every number is the Orchestrator's. The other
+                  containers' shares ride their own fragments — Sidecars and
+                  InitContainers are whole Containers, `resources` included.
                 properties:
                   claims:
                     description: |-
@@ -2521,6 +2629,21 @@ spec:
                         type: string
                     type: object
                 type: object
+              shmSize:
+                anyOf:
+                - type: integer
+                - type: string
+                description: |-
+                  ShmSize is the sizeLimit of the memory-backed emptyDir the operator
+                  mounts at /dev/shm in the primary container only (ADR-0060). The
+                  Orchestrator computes it from the Harness's share; shm is charged inside
+                  that container's memory limit, so it reserves nothing extra, and a full
+                  shm is ENOSPC or SIGBUS — a tool error, never a memory kill. Unset
+                  mounts nothing and leaves the runtime's own /dev/shm: an unbounded
+                  memory emptyDir is never the default, because filling it kills the
+                  container.
+                pattern: ^(\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\+|-)?(([0-9]+(\.[0-9]*)?)|(\.[0-9]+))))?$
+                x-kubernetes-int-or-string: true
               sidecars:
                 description: |-
                   Sidecars are generic Kubernetes container fragments scheduled alongside
@@ -6070,8 +6193,14 @@ spec:
             description: status defines the observed state of Sandbox
             properties:
               conditions:
-                description: Conditions represent the current state of the Sandbox
-                  resource.
+                description: |-
+                  Conditions represent the current state of the Sandbox resource: Ready
+                  (the gate), ReposFresh (the Repo gate's verdict), Scheduled — the Pod's
+                  PodScheduled condition restated with the scheduler's own reason and
+                  message, or QuotaExceeded with the API server's words while a
+                  ResourceQuota refuses the Pod, so a Pending Sandbox says why it waits
+                  (ADR-0063, ADR-0064) — and Lost, True with the reason and the Pod's own
+                  words once the phase is Lost (ADR-0021).
                 items:
                   description: Condition contains details for one aspect of the current
                     state of this API Resource.
@@ -6130,27 +6259,109 @@ spec:
                 x-kubernetes-list-map-keys:
                 - type
                 x-kubernetes-list-type: map
+              effector:
+                description: |-
+                  Effector is the same report for the sidecar named "effector", the
+                  Sandbox Effector (ADR-0068): its restarts and how it last ended. An
+                  Effector that cannot serve says why in its termination message — a
+                  node whose kernel cannot confine a credentialed command's child says
+                  `landlock: unavailable on node <node> (...)` — so a provision fails on
+                  it before any Turn. Absent when the pod has no Effector, or until the
+                  kubelet reports it.
+                properties:
+                  lastTerminated:
+                    description: |-
+                      LastTerminated is how the container's previous run ended — the Pod's
+                      `lastState.terminated`. Absent while the container has never restarted.
+                    properties:
+                      exitCode:
+                        description: ExitCode is the run's exit code (137 for a kernel
+                          kill).
+                        format: int32
+                        type: integer
+                      finishedAt:
+                        description: FinishedAt is when the run ended.
+                        format: date-time
+                        type: string
+                      message:
+                        description: |-
+                          Message is the kubelet's termination message. For the Harness container
+                          it is the run's last log lines (`FallbackToLogsOnError`, ADR-0063), so a
+                          Harness that dies before Ready is named in its own words.
+                        type: string
+                      reason:
+                        description: Reason is the kubelet's reason, e.g. `OOMKilled`,
+                          `Error`, `Completed`.
+                        type: string
+                    type: object
+                  restartCount:
+                    description: RestartCount is the container's restartCount on the
+                      Sandbox's Pod.
+                    format: int32
+                    type: integer
+                type: object
               endpoint:
                 description: |-
                   Endpoint is the in-cluster Service DNS the Orchestrator uses to reach the
                   Harness, e.g. http://<name>.<ns>.svc:8080.
                 type: string
+              harness:
+                description: |-
+                  Harness is what the kubelet reports about the primary container of the
+                  Pod status.podUID names (ADR-0063): its restarts and how it last ended.
+                  The Orchestrator never reads a Pod; this is how it tells a
+                  crash-looping Harness, and a memory kill (`OOMKilled`, ADR-0061), from
+                  a lost conversation. Absent until the kubelet reports the container.
+                properties:
+                  lastTerminated:
+                    description: |-
+                      LastTerminated is how the container's previous run ended — the Pod's
+                      `lastState.terminated`. Absent while the container has never restarted.
+                    properties:
+                      exitCode:
+                        description: ExitCode is the run's exit code (137 for a kernel
+                          kill).
+                        format: int32
+                        type: integer
+                      finishedAt:
+                        description: FinishedAt is when the run ended.
+                        format: date-time
+                        type: string
+                      message:
+                        description: |-
+                          Message is the kubelet's termination message. For the Harness container
+                          it is the run's last log lines (`FallbackToLogsOnError`, ADR-0063), so a
+                          Harness that dies before Ready is named in its own words.
+                        type: string
+                      reason:
+                        description: Reason is the kubelet's reason, e.g. `OOMKilled`,
+                          `Error`, `Completed`.
+                        type: string
+                    type: object
+                  restartCount:
+                    description: RestartCount is the container's restartCount on the
+                      Sandbox's Pod.
+                    format: int32
+                    type: integer
+                type: object
               node:
                 description: |-
                   Node is the node the Pod was scheduled onto, once it was — the node
                   whose Repo caches this Sandbox mounts, and so the key into each named
                   Repo's `status.nodes[]` for whoever reads the Sandbox — a human at
-                  `kubectl get`. Nothing in the control plane reads it back:
-                  the operator places and gates on the Pod's own `spec.nodeName`, and the
-                  cache agent takes demand off the pods on its node, never off a Sandbox
-                  (ADR-0051).
+                  `kubectl get`. The operator reads it back only to choose which
+                  Sandboxes a Repo's status write wakes (ADR-0001); it places and gates
+                  on the Pod's own `spec.nodeName`, and the cache agent takes demand off
+                  the pods on its node, never off a Sandbox (ADR-0051).
                 type: string
               phase:
-                description: 'Phase is a coarse lifecycle summary: Pending -> Ready
-                  -> Terminating.'
+                description: |-
+                  Phase is a coarse lifecycle summary: Pending -> Ready -> Terminating,
+                  or Lost from Pending or Ready once the Pod is gone or terminal (ADR-0021).
                 enum:
                 - Pending
                 - Ready
+                - Lost
                 - Terminating
                 type: string
               podRef:
@@ -6169,19 +6380,18 @@ spec:
                 x-kubernetes-map-type: atomic
               podUID:
                 description: |-
-                  PodUID is the identity of the Pod backing this Sandbox. Pod names are
-                  deterministic, so a name alone cannot distinguish the Pod a client
-                  attached to from a replacement scheduled after an eviction or node loss —
-                  and a replacement comes up with an empty `work` volume, so every clone,
-                  worktree, and unpushed commit is gone. The UID changes exactly when that
-                  happens, which is what lets a client detect it (ADR-0021).
+                  PodUID is the identity of the one Pod the operator created for this
+                  Sandbox (ADR-0021). Set once, when that Pod is created, and never
+                  changed: it is how the operator knows, across its own restarts, that the
+                  Pod was already created once — so a Pod that is later absent is Lost, never
+                  created again. Clients read phase Lost, not a UID comparison.
                 type: string
               repos:
                 description: |-
                   Repos is the standing report on the caches this Sandbox mounts
                   (ADR-0053), one entry per key in spec.repos, in that order, computed on
                   every reconcile once the Pod has a node. It is what a fetch inside the
-                  pod waits on: the program asks the Adapter, the Orchestrator marks the
+                  pod waits on: the program asks the Custodian, the Orchestrator marks the
                   ask on this CR, and the entry for that key says whether the node fetched
                   since. `Ready` is untouched by it — that stays the gate it was, sticky
                   and taken once per Pod life; this is the standing answer the gate's
@@ -6248,6 +6458,38 @@ spec:
                     type: string
                 type: object
                 x-kubernetes-map-type: atomic
+              waiting:
+                description: |-
+                  Waiting is every container of the current Pod that is waiting, init
+                  containers first, with the kubelet's reason and message (ADR-0063). A
+                  container that never starts — a root image under runAsNonRoot, a bad
+                  image name, a pull that keeps failing — leaves no log and no
+                  termination, so this is the Orchestrator's only evidence of it. Copied,
+                  not judged: the Orchestrator decides which reasons end a provision.
+                items:
+                  description: SandboxContainerWaiting is one waiting container, in
+                    the kubelet's words.
+                  properties:
+                    container:
+                      description: Container is the container's name, e.g. `preflight`,
+                        `harness`.
+                      type: string
+                    message:
+                      description: Message is the kubelet's message, when it gives
+                        one.
+                      type: string
+                    reason:
+                      description: |-
+                        Reason is the kubelet's reason, e.g. `CreateContainerConfigError`,
+                        `ImagePullBackOff`, `PodInitializing`.
+                      type: string
+                  required:
+                  - container
+                  type: object
+                type: array
+                x-kubernetes-list-map-keys:
+                - container
+                x-kubernetes-list-type: map
             type: object
         required:
         - spec
@@ -6648,11 +6890,10 @@ spec:
           periodSeconds: 10
         resources:
           limits:
-            cpu: 500m
-            memory: 128Mi
+            memory: 256Mi
           requests:
-            cpu: 10m
-            memory: 64Mi
+            cpu: 50m
+            memory: 256Mi
         securityContext:
           allowPrivilegeEscalation: false
           capabilities:
@@ -6660,6 +6901,7 @@ spec:
             - ALL
           readOnlyRootFilesystem: true
         volumeMounts: []
+      priorityClassName: jr2-control
       securityContext:
         runAsNonRoot: true
         seccompProfile:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jr2/cli",
-  "version": "0.2.1",
+  "version": "0.4.1",
   "description": "The jr2 CLI: init, up, run — the interface to a jr2 Instance.",
   "license": "MIT",
   "private": false,
@@ -39,13 +39,14 @@
     "ts-blank-space": "^0.9.0"
   },
   "peerDependencies": {
-    "@jr2/orchestrator": "0.2.1"
+    "@jr2/orchestrator": "0.4.1"
   },
   "devDependencies": {
+    "@anthropic-ai/sdk": "0.91.1",
     "@types/node": "^26.0.1",
     "xstate": "^5.18.0",
     "zod": "^4.4.3",
-    "@jr2/orchestrator": "0.2.1"
+    "@jr2/orchestrator": "0.4.1"
   },
   "files": [
     "bin",
@@ -54,6 +55,7 @@
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "node --test"
+    "test": "node --test --test-global-setup=../../scripts/test-tmpdir.ts 'test/**/*.test.ts'",
+    "test:custodian": "node --test --test-global-setup=../../scripts/test-tmpdir.ts --test-concurrency=1 test/custodian.docker.ts"
   }
 }