Skip to content

Commit 1560ea2

Browse files
committed
feat(cli): name failing assets and drift cause on actor_guidance_unverified refusals
Fixes #384
1 parent 56479df commit 1560ea2

3 files changed

Lines changed: 293 additions & 2 deletions

File tree

‎docs/operating.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,15 @@ Default mode touches nothing — run the plan first, read it, then decide. `--ap
102102

103103
A plan or apply that hits an asset without verified Cortex ownership reports `operation=<logical id> action=conflict` and ends with `status=conflict conflict_paths=<relative path,...>` (exit 3), naming each conflicting asset by its path under the runtime root. Nothing is written; stop and ask the user rather than removing the file.
104104

105+
When a guidance preflight or apply re-check refuses, the plan prints `status=conflict reason=actor_guidance_unverified` (exit 3) followed by one `asset=` line per failing asset naming the failing file and the cause:
106+
107+
```
108+
asset=skills/adversarial-tester path=skills/cortex-adversarial-tester/SKILL.md cause=content_drift action=conflict
109+
asset=skills/requirements-analyst path=skills/cortex-requirements-analyst/SKILL.md cause=mode_drift observed_mode=0640 canonical_mode=0600
110+
```
111+
112+
`cause=content_drift` means the bytes differ from the recorded state; `cause=mode_drift` reports the observed versus canonical file mode. Shadow conflicts (externally authored files under Cortex-owned identities) report `cause=shadow_role` with the shadow location. Paths are runtime-relative.
113+
105114
## Upgrade to alpha20
106115

107116
Use the [published alpha20 archive and checksum procedure](verification.md#verify-an-archive) for the machine's platform. Keep the extracted binary, catalog and licenses together in a versioned directory. Do not replace user model routes or runtime configuration with release defaults.

‎internal/cli/update.go‎

Lines changed: 83 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -518,8 +518,7 @@ func updateActorGuidance(stdout, stderr io.Writer, canonical installplan.Plan, o
518518
}
519519
preflight, err := installcoord.PreflightActorGuidance(observations, installcoord.Unit{Plan: canonical, Observation: observation}, adopt, cwd)
520520
if err != nil || !preflight.Report().Ready() {
521-
_, _ = fmt.Fprintf(stdout, "%s\nstatus=conflict reason=actor_guidance_unverified\n", header)
522-
return exitConflict
521+
return writeActorGuidanceRefusal(stdout, header, canonical, preflight.Refusal())
523522
}
524523
proof := preflight.Proof() // Retain the exact immutable candidate and evidence.
525524
if !apply {
@@ -547,3 +546,85 @@ func updateActorGuidance(stdout, stderr io.Writer, canonical installplan.Plan, o
547546
func nextUpdateBackupName() string {
548547
return "install-" + strconv.FormatInt(time.Now().UnixNano(), 36)
549548
}
549+
550+
// writeActorGuidanceRefusal reports one refused actor-guidance update. The
551+
// stable status line, the opaque stderr contract, and exitConflict are
552+
// unchanged; the additive asset= diagnostics name each asset that failed
553+
// verification and why, so reason=actor_guidance_unverified is never the only
554+
// evidence the operator gets (issue #373, spec S2/S4/S5).
555+
func writeActorGuidanceRefusal(stdout io.Writer, header string, canonical installplan.Plan, refusal installcoord.ActorGuidanceRefusal) int {
556+
output := strings.Builder{}
557+
output.WriteString(header + "\n")
558+
for _, line := range actorGuidanceRefusalAssets(canonical, refusal) {
559+
output.WriteString(line + "\n")
560+
}
561+
output.WriteString("status=conflict reason=actor_guidance_unverified\n")
562+
_, _ = io.WriteString(stdout, output.String())
563+
return exitConflict
564+
}
565+
566+
// actorGuidanceRefusalAssets renders one machine-readable diagnostic line per
567+
// asset that failed verification: content drift, mode drift with both modes, or
568+
// the bounded role/location that shadows a closed actor. A conflicting asset
569+
// that also drifted in mode keeps its content-drift cause and still reports the
570+
// mode facts. Paths stay runtime-relative (S5); the writer names nothing the
571+
// preflight did not capture.
572+
func actorGuidanceRefusalAssets(canonical installplan.Plan, refusal installcoord.ActorGuidanceRefusal) []string {
573+
assets, shadows := refusal.Assets(), refusal.Shadows()
574+
lines := make([]string, 0, len(assets)+len(shadows))
575+
for _, asset := range assets {
576+
line := actorGuidanceAsset(asset.LogicalID, asset.RelativePath)
577+
if asset.Cause == installcoord.ActorGuidanceModeDrift {
578+
lines = append(lines, line+" cause=mode_drift mode_drift=true"+actorGuidanceModes(asset))
579+
continue
580+
}
581+
line += " cause=content_drift action=conflict"
582+
if asset.ModeDrift {
583+
line += " mode_drift=true" + actorGuidanceModes(asset)
584+
}
585+
lines = append(lines, line)
586+
}
587+
relative := make(map[string]string, len(canonical.Files()))
588+
for _, file := range canonical.Files() {
589+
relative[file.LogicalID()] = file.RelativePath()
590+
}
591+
for _, shadow := range shadows {
592+
logicalID := "actors/" + string(shadow.RoleID())
593+
lines = append(lines, actorGuidanceAsset(logicalID, relative[logicalID])+" cause=shadow_role shadow_location="+actorGuidanceShadowLocation(shadow.Location()))
594+
}
595+
return lines
596+
}
597+
598+
// actorGuidanceModes renders the captured and canonical modes of one asset, in
599+
// the same shape the update operation lines already use.
600+
func actorGuidanceModes(asset installcoord.ActorGuidanceRefusalAsset) string {
601+
return fmt.Sprintf(" observed_mode=%04o canonical_mode=%04o", asset.ObservedMode, asset.CanonicalMode)
602+
}
603+
604+
// actorGuidanceAsset renders the `asset=<logical ID> path=<runtime-relative>`
605+
// prefix of one diagnostic line, omitting the path when the candidate carries no
606+
// file for that identity instead of inventing one.
607+
func actorGuidanceAsset(logicalID, path string) string {
608+
if path != "" {
609+
return fmt.Sprintf("asset=%s path=%s", logicalID, path)
610+
}
611+
return "asset=" + logicalID
612+
}
613+
614+
// actorGuidanceShadowLocation names the bounded root a shadow conflict was
615+
// found in. The scan exposes no path, so the location stays a closed symbolic
616+
// name instead of an absolute one (S5).
617+
func actorGuidanceShadowLocation(location installobserve.ShadowLocation) string {
618+
switch location {
619+
case installobserve.ShadowLocationGlobalAgents:
620+
return "global_agents"
621+
case installobserve.ShadowLocationGlobalSubagents:
622+
return "global_subagents"
623+
case installobserve.ShadowLocationProjectAgents:
624+
return "project_agents"
625+
case installobserve.ShadowLocationProjectSubagents:
626+
return "project_subagents"
627+
default:
628+
return "unknown"
629+
}
630+
}

‎internal/cli/update_guidance_test.go‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -132,6 +132,207 @@ func TestUpdateGuidanceLifecycle(t *testing.T) {
132132
}
133133
}
134134

135+
// updateRegistersGuidance seeds one Pi installation and registers pre-existing
136+
// external guidance through the explicit adoption apply, so later runs exercise
137+
// the registered v3 update path instead of the first-adoption path.
138+
func updateRegistersGuidance(t *testing.T, fixture *updateFixture) (string, updateDependencies) {
139+
t.Helper()
140+
fixture.catalog = must(filepath.Abs(fixture.catalog))
141+
t.Chdir(must(filepath.EvalSymlinks(t.TempDir())))
142+
root, deps := updateRootPath(t, fixture, runtimematrix.RuntimePi), fixture.dependencies(runtimematrix.RuntimePi)
143+
if code, out, err := runUpdateCommand(t, deps, "update", "--runtime", "pi", "--catalog", fixture.catalog, "--apply"); code != exitOK || err != "" {
144+
t.Fatalf("seed apply = (%d, %q, %q)", code, out, err)
145+
}
146+
for _, artifact := range updateStateIdentity(t, root).Artifacts() {
147+
if artifact.Kind() != installstate.KindPiActor {
148+
continue
149+
}
150+
path := filepath.Join(root, filepath.FromSlash(artifact.RelativePath()))
151+
mustOK(os.WriteFile(path, append(bytes.TrimRight(must(os.ReadFile(path)), "\n"), updateGuidanceSuffix...), 0o600))
152+
}
153+
if code, out, err := runUpdateCommand(t, deps, "update", "--runtime", "pi", "--catalog", fixture.catalog, "--adopt-guidance", "--apply"); code != exitOK || err != "" {
154+
t.Fatalf("adoption apply = (%d, %q, %q)", code, out, err)
155+
}
156+
if state := updateStateIdentity(t, root); state.SchemaVersion() != 3 {
157+
t.Fatalf("registered guidance state = v%d, want v3", state.SchemaVersion())
158+
}
159+
return root, deps
160+
}
161+
162+
// updateGuidanceDiagnostics returns the additive per-asset refusal lines keyed
163+
// by asset, and fails when a line carries an absolute path (issue #373, S5).
164+
func updateGuidanceDiagnostics(t *testing.T, root, out string) map[string]string {
165+
t.Helper()
166+
lines := map[string]string{}
167+
for _, line := range strings.Split(out, "\n") {
168+
if !strings.HasPrefix(line, "asset=") {
169+
continue
170+
}
171+
fields := map[string]string{}
172+
for _, field := range strings.Fields(line) {
173+
key, asset, found := strings.Cut(field, "=")
174+
if !found {
175+
t.Fatalf("diagnostic %q is not machine-readable", line)
176+
}
177+
fields[key] = asset
178+
}
179+
path := fields["path"]
180+
if path == "" || filepath.IsAbs(path) || strings.HasPrefix(path, root+"/") {
181+
t.Fatalf("diagnostic %q does not carry a runtime-relative path", line)
182+
}
183+
lines[fields["asset"]] = line
184+
}
185+
return lines
186+
}
187+
188+
// TestUpdateGuidanceRefusalNamesDriftedContent pins spec S2 for issue #373: a
189+
// refused guidance update names every asset whose content drifted from the
190+
// recorded identity, keeps the stable reason token, exit code, and opaque
191+
// stderr, and writes nothing.
192+
func TestUpdateGuidanceRefusalNamesDriftedContent(t *testing.T) {
193+
fixture := newUpdateFixture(t)
194+
root, deps := updateRegistersGuidance(t, fixture)
195+
var drifted installstate.Artifact
196+
for _, artifact := range updateStateIdentity(t, root).Artifacts() {
197+
if artifact.Kind() == installstate.KindPiActor {
198+
drifted = artifact
199+
break
200+
}
201+
}
202+
path := filepath.Join(root, filepath.FromSlash(drifted.RelativePath()))
203+
mustOK(os.WriteFile(path, append(must(os.ReadFile(path)), []byte("drift")...), 0o600))
204+
before := updateGuidanceTree(t, fixture.home)
205+
for _, flags := range [][]string{nil, {"--apply"}} {
206+
args := append([]string{"update", "--runtime", "pi", "--catalog", fixture.catalog}, flags...)
207+
code, out, err := runUpdateCommand(t, deps, args...)
208+
if code != exitConflict || err != "" || !strings.Contains(out, "status=conflict reason=actor_guidance_unverified") {
209+
t.Fatalf("drift refusal %v = (%d, %q, %q)", flags, code, out, err)
210+
}
211+
line, found := updateGuidanceDiagnostics(t, root, out)[drifted.LogicalID()]
212+
if !found || !strings.Contains(line, "path="+drifted.RelativePath()) || !strings.Contains(line, "cause=content_drift") || !strings.Contains(line, "action=conflict") {
213+
t.Fatalf("refusal %q did not name the drifted asset %s as content drift: %q", out, drifted.LogicalID(), line)
214+
}
215+
if !reflect.DeepEqual(before, updateGuidanceTree(t, fixture.home)) {
216+
t.Fatal("refused guidance update wrote files")
217+
}
218+
}
219+
}
220+
221+
// TestUpdateGuidanceRefusalNamesModeDrift pins the mode-drift half of spec S2:
222+
// an asset whose observed mode diverged is named with both modes instead of the
223+
// bare unverified token.
224+
func TestUpdateGuidanceRefusalNamesModeDrift(t *testing.T) {
225+
fixture := newUpdateFixture(t)
226+
root, deps := updateRegistersGuidance(t, fixture)
227+
var drifted installstate.Artifact
228+
for _, artifact := range updateStateIdentity(t, root).Artifacts() {
229+
if artifact.Kind() == installstate.KindPiActor {
230+
drifted = artifact
231+
break
232+
}
233+
}
234+
mustOK(os.Chmod(filepath.Join(root, filepath.FromSlash(drifted.RelativePath())), 0o640))
235+
before := updateGuidanceTree(t, fixture.home)
236+
code, out, err := runUpdateCommand(t, deps, "update", "--runtime", "pi", "--catalog", fixture.catalog)
237+
if code != exitConflict || err != "" || !strings.Contains(out, "status=conflict reason=actor_guidance_unverified") {
238+
t.Fatalf("mode drift refusal = (%d, %q, %q)", code, out, err)
239+
}
240+
line, found := updateGuidanceDiagnostics(t, root, out)[drifted.LogicalID()]
241+
if !found || !strings.Contains(line, "path="+drifted.RelativePath()) || !strings.Contains(line, "cause=mode_drift") || !strings.Contains(line, "observed_mode=0640 canonical_mode=0600") {
242+
t.Fatalf("refusal %q did not name the mode-drifted asset %s: %q", out, drifted.LogicalID(), line)
243+
}
244+
if !reflect.DeepEqual(before, updateGuidanceTree(t, fixture.home)) {
245+
t.Fatal("refused guidance update wrote files")
246+
}
247+
}
248+
249+
// TestUpdateGuidanceRefusalNamesContentAndModeDrift pins the combined case: when
250+
// an asset drifted in content and in mode, the refusal names the content drift
251+
// as the conflict and still carries the mode facts it also captured, instead of
252+
// dropping one of the two causes (issue #373, S2).
253+
func TestUpdateGuidanceRefusalNamesContentAndModeDrift(t *testing.T) {
254+
fixture := newUpdateFixture(t)
255+
root, deps := updateRegistersGuidance(t, fixture)
256+
var drifted installstate.Artifact
257+
for _, artifact := range updateStateIdentity(t, root).Artifacts() {
258+
if artifact.Kind() == installstate.KindSkill {
259+
drifted = artifact
260+
break
261+
}
262+
}
263+
path := filepath.Join(root, filepath.FromSlash(drifted.RelativePath()))
264+
mustOK(os.WriteFile(path, append(must(os.ReadFile(path)), []byte("drift")...), 0o640))
265+
mustOK(os.Chmod(path, 0o640))
266+
before := updateGuidanceTree(t, fixture.home)
267+
code, out, err := runUpdateCommand(t, deps, "update", "--runtime", "pi", "--catalog", fixture.catalog)
268+
if code != exitConflict || err != "" || !strings.Contains(out, "status=conflict reason=actor_guidance_unverified") {
269+
t.Fatalf("combined drift refusal = (%d, %q, %q)", code, out, err)
270+
}
271+
line, found := updateGuidanceDiagnostics(t, root, out)[drifted.LogicalID()]
272+
for _, want := range []string{"path=" + drifted.RelativePath(), "cause=content_drift", "action=conflict", "mode_drift=true", "observed_mode=0640 canonical_mode=0600"} {
273+
if !found || !strings.Contains(line, want) {
274+
t.Fatalf("refusal %q did not report %q for %s: %q", out, want, drifted.LogicalID(), line)
275+
}
276+
}
277+
if !reflect.DeepEqual(before, updateGuidanceTree(t, fixture.home)) {
278+
t.Fatal("refused guidance update wrote files")
279+
}
280+
}
281+
282+
// TestUpdateGuidanceEvidenceRefusalNamesContentBeforeModeDrift pins issue #384:
283+
// on the evidence stage an actor whose bytes and mode both drifted reports the
284+
// content drift as its cause and carries the mode facts, so one refusal names
285+
// both causes instead of hiding the content drift behind the mode drift.
286+
func TestUpdateGuidanceEvidenceRefusalNamesContentBeforeModeDrift(t *testing.T) {
287+
fixture := newUpdateFixture(t)
288+
root, deps := updateRegistersGuidance(t, fixture)
289+
var drifted installstate.Artifact
290+
for _, artifact := range updateStateIdentity(t, root).Artifacts() {
291+
if artifact.Kind() == installstate.KindPiActor {
292+
drifted = artifact
293+
break
294+
}
295+
}
296+
path := filepath.Join(root, filepath.FromSlash(drifted.RelativePath()))
297+
mustOK(os.WriteFile(path, append(must(os.ReadFile(path)), []byte("drift")...), 0o640))
298+
mustOK(os.Chmod(path, 0o640))
299+
before := updateGuidanceTree(t, fixture.home)
300+
code, out, err := runUpdateCommand(t, deps, "update", "--runtime", "pi", "--catalog", fixture.catalog)
301+
if code != exitConflict || err != "" || !strings.Contains(out, "status=conflict reason=actor_guidance_unverified") {
302+
t.Fatalf("combined evidence refusal = (%d, %q, %q)", code, out, err)
303+
}
304+
want := "asset=" + drifted.LogicalID() + " path=" + drifted.RelativePath() + " cause=content_drift action=conflict mode_drift=true observed_mode=0640 canonical_mode=0600"
305+
if line := updateGuidanceDiagnostics(t, root, out)[drifted.LogicalID()]; line != want {
306+
t.Fatalf("refusal %q line for %s = %q, want %q", out, drifted.LogicalID(), line, want)
307+
}
308+
if !reflect.DeepEqual(before, updateGuidanceTree(t, fixture.home)) {
309+
t.Fatal("refused guidance update wrote files")
310+
}
311+
}
312+
313+
// TestUpdateGuidanceRefusalNamesShadowedRole pins the distinguishing half of
314+
// spec S2: a shadow refusal names the closed role and the bounded location that
315+
// shadows it, never an absolute path.
316+
func TestUpdateGuidanceRefusalNamesShadowedRole(t *testing.T) {
317+
fixture := newUpdateFixture(t)
318+
root, deps := updateRegistersGuidance(t, fixture)
319+
cwd := must(os.Getwd())
320+
mustOK(os.MkdirAll(filepath.Join(cwd, ".pi", "subagents"), 0o700))
321+
mustOK(os.WriteFile(filepath.Join(cwd, ".pi", "subagents", "shadow.md"), []byte("---\nname: cortex-test-designer\n---\n"), 0o600))
322+
before := updateGuidanceTree(t, fixture.home)
323+
code, out, err := runUpdateCommand(t, deps, "update", "--runtime", "pi", "--catalog", fixture.catalog)
324+
if code != exitConflict || err != "" || !strings.Contains(out, "status=conflict reason=actor_guidance_unverified") {
325+
t.Fatalf("shadow refusal = (%d, %q, %q)", code, out, err)
326+
}
327+
line, found := updateGuidanceDiagnostics(t, root, out)["actors/test-designer"]
328+
if !found || !strings.Contains(line, "cause=shadow_role") || !strings.Contains(line, "shadow_location=project_subagents") {
329+
t.Fatalf("refusal %q did not name the shadowed role: %q", out, line)
330+
}
331+
if !reflect.DeepEqual(before, updateGuidanceTree(t, fixture.home)) {
332+
t.Fatal("refused guidance update wrote files")
333+
}
334+
}
335+
135336
func TestUpdateGuidanceProductionApplyRechecks(t *testing.T) {
136337
for _, scenario := range []string{"actor", "skill", "state", "shadow"} {
137338
t.Run(scenario, func(t *testing.T) {

0 commit comments

Comments
 (0)