Mark cleanup roadmap stages as implemented

docs/roadmap/cleanup.md

@@ -1,6 +1,6 @@
 # Roadmap: Pre-1.0 Code Cleanup
 
-Status: Planned
+Status: Implemented
 
 This roadmap turns the remaining findings in `docs/roadmap/audit.md` into decision-complete implementation stages. It follows the policy documents under `docs/policy/` and preserves current public CLI, config, storage layout, manifest, and stage behavior unless a stage explicitly says otherwise.
 
@@ -22,7 +22,7 @@ This roadmap turns the remaining findings in `docs/roadmap/audit.md` into decisi
 - Do not add compatibility aliases for retired archive/promote, campaign, transcript, or previous-session source names.
 - Do not move restore's remote-key include/exclude policy out of restore unless another caller is added.
 
-## Stage 1: Path and File Mechanics
+## Stage 1: Path and File Mechanics (Implemented)
 
 Add shared mechanics for root-scoped path safety and atomic file operations.
 
@@ -64,7 +64,7 @@ Acceptance criteria:
 - Atomic helper tests prove temp files are cleaned up on failure and checksums match final file contents.
 - Restore, prepare, and audio cache behavior remain unchanged.
 
-## Stage 2: Artifact Source Policy
+## Stage 2: Artifact Source Policy (Implemented)
 
 Finish centralizing artifact source vocabulary and validation in `internal/artifactpolicy`.
 
@@ -103,7 +103,7 @@ Acceptance criteria:
 - Analyze behavior for required/optional built-in, configured, and previous-session sources is unchanged.
 - Previous-cache candidate ordering and required/optional behavior are unchanged.
 
-## Stage 3: Read-Only Inspection Layer
+## Stage 3: Read-Only Inspection Layer (Implemented)
 
 Extract shared read-only session inspection checks for `session validate` and `session status`.
 
@@ -137,7 +137,7 @@ Acceptance criteria:
 - Missing current run pointer/manifest behavior remains command-appropriate: validation reports an error; status reports unavailable state.
 - Existing lock and remote current-state behavior is unchanged.
 
-## Stage 4: Optional CLI Edge Cleanup
+## Stage 4: Optional CLI Edge Cleanup (Implemented)
 
 Only implement this stage if Stage 1-3 leave meaningful repeated parser code.
 
@@ -159,7 +159,7 @@ Acceptance criteria:
 - Missing source arguments for lock add/remove remain clear.
 - No new command aliases are introduced.
 
-## Stage 5: Final Sweep
+## Stage 5: Final Sweep (Implemented)
 
 Run final validation after the implementation stages.
 

internal/app/operator_findings.go

@@ -10,7 +10,6 @@ import (
 	"strings"
 
 	"gitea.maximumdirect.net/eric/narratio/internal/adapters/storage"
-	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
 	"gitea.maximumdirect.net/eric/narratio/internal/config"
 	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
 )
@@ -64,26 +63,18 @@ func sessionSourceSummary(cfg *config.Config) string {
 }
 
 func validateStableInputFindings(cfg *config.Config) []finding {
-	items := []struct {
-		name string
-		in   config.ResolvedInputFile
-	}{
-		{"speakers", cfg.StableInputs.SpeakersFile},
-		{"autocorrect", cfg.StableInputs.AutocorrectFile},
-		{"glossary", cfg.StableInputs.GlossaryFile},
+	checks := inspectStableInputs(cfg)
+	out := make([]finding, 0, len(checks))
+	for _, check := range checks {
+		if check.Err != nil {
+			msg := check.Name + ": " + check.Err.Error()
+			if strings.TrimSpace(check.Path) != "" {
+				msg = fmt.Sprintf("%s missing: %v", check.Name, check.Err)
 			}
-	out := make([]finding, 0, len(items))
-	for _, item := range items {
-		path, err := resolveHelperConfigRelativePath(item.in)
-		if err != nil {
-			out = append(out, errorFinding("inputs", item.name+": "+err.Error()))
+			out = append(out, errorFinding("inputs", msg))
 			continue
 		}
-		if _, err := os.Stat(path); err != nil {
-			out = append(out, errorFinding("inputs", fmt.Sprintf("%s missing: %v", item.name, err)))
-		} else {
-			out = append(out, okFinding("inputs", item.name+": "+path))
-		}
+		out = append(out, okFinding("inputs", check.Name+": "+check.Path))
 	}
 	return out
 }
@@ -103,76 +94,22 @@ func resolveHelperConfigRelativePath(input config.ResolvedInputFile) (string, er
 }
 
 func validateLocalAudioFindings(cfg *config.Config) []finding {
-	if cfg.Session.Inputs.AudioS3 != nil {
+	check := inspectLocalAudioPresence(cfg)
+	if !check.Checked {
 		return nil
 	}
-	audioDir := strings.TrimSpace(cfg.Session.Inputs.AudioDir)
-	if audioDir == "" && len(cfg.Session.Inputs.AudioFiles) == 0 {
-		return []finding{errorFinding("audio", "audio_dir, audio_files, or audio_s3 is required")}
+	if check.Err != nil {
+		return []finding{errorFinding("audio", check.Err.Error())}
 	}
-	base := filepath.Dir(cfg.SessionPath)
-	paths := []string{}
-	if audioDir != "" {
-		dir := audioDir
-		if !filepath.IsAbs(dir) {
-			dir = filepath.Join(base, dir)
-		}
-		matches, err := filepath.Glob(filepath.Join(dir, "*.flac"))
-		if err != nil || len(matches) == 0 {
-			return []finding{errorFinding("audio", "no .flac files found in "+dir)}
-		}
-		paths = append(paths, matches...)
-	}
-	for _, file := range cfg.Session.Inputs.AudioFiles {
-		p := file
-		if !filepath.IsAbs(p) {
-			p = filepath.Join(base, p)
-		}
-		paths = append(paths, p)
-	}
-	for _, p := range paths {
-		if _, err := os.Stat(p); err != nil {
-			return []finding{errorFinding("audio", fmt.Sprintf("audio file missing: %v", err))}
-		}
-	}
-	return []finding{okFinding("audio", fmt.Sprintf("%d local audio file(s)", len(paths)))}
+	return []finding{okFinding("audio", fmt.Sprintf("%d local audio file(s)", len(check.Paths)))}
 }
 
 func validateRemoteAudioFinding(ctx context.Context, cfg *config.Config, store storage.ObjectStore) finding {
-	sessionPrefix := artifacts.S3SessionPrefix(cfg.Pipeline.Storage.S3.RootPrefix, cfg.Session.Campaign, cfg.Session.SessionID)
-	audioPrefix := artifacts.S3AudioPrefix(sessionPrefix, cfg.Session.Inputs.AudioS3.Prefix)
-	objects, err := store.List(ctx, audioPrefix)
-	if err != nil {
-		return errorFinding("audio", err.Error())
+	check := inspectRemoteAudioPresence(ctx, cfg, store)
+	if check.Err != nil {
+		return errorFinding("audio", check.Err.Error())
 	}
-	count := 0
-	for _, obj := range objects {
-		if strings.HasSuffix(strings.ToLower(obj.Key), ".flac") {
-			count++
-		}
-	}
-	if count == 0 {
-		return errorFinding("audio", "no remote .flac objects found under "+audioPrefix)
-	}
-	return okFinding("audio", fmt.Sprintf("%d remote .flac object(s)", count))
-}
-
-func validatePreviousArtifactFindings(ctx context.Context, cfg *config.Config, store storage.ObjectStore, requirements []artifacts.PreviousArtifactRequirement) []finding {
-	out := []finding{}
-	prefix := artifacts.S3SessionPrefix(cfg.Pipeline.Storage.S3.RootPrefix, cfg.Session.Campaign, cfg.Session.PreviousSessionID)
-	_, err := artifacts.LoadCurrentState(ctx, store, prefix, artifacts.CurrentStateValidation{
-		ExpectedSessionID: strings.TrimSpace(cfg.Session.PreviousSessionID),
-		ExpectedCampaign:  strings.TrimSpace(cfg.Session.Campaign),
-		ValidateRunID:     true,
-	})
-	if err != nil {
-		out = append(out, errorFinding("previous", fmt.Sprintf("remote %v", err)))
-		return out
-	}
-	for _, req := range requirements {
-		out = append(out, okFinding("previous", fmt.Sprintf("%s required=%t", req.Name, req.Required)))
-	}
-	return out
+	return okFinding("audio", fmt.Sprintf("%d remote .flac object(s)", len(check.Keys)))
 }
 
 func loadLocalManifest(ctx context.Context, path string) (*manifest.Manifest, error) {

internal/app/operator_helpers_test.go

@@ -593,6 +593,53 @@ func TestExecuteLocksRequireSessionID(t *testing.T) {
 	}
 }
 
+func TestExecuteLocksMutationRejectsSessionIDMismatch(t *testing.T) {
+	workspaceRoot := t.TempDir()
+	pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot)
+	fake := &storage.FakeBackend{}
+	var storeInitCalls int
+	restoreAppConfigTestGlobals(t, fake, &storeInitCalls, []string{sessionPath})
+
+	tests := []struct {
+		name string
+		args []string
+	}{
+		{
+			name: "add mismatch",
+			args: []string{
+				"session", "locks", "add", "2026-05-03", "narratio.transcript.final_trimmed",
+				"--session-id", "2026-05-04",
+				"--config", pipelinePath,
+				"--campaign-file", campaignPath,
+				"--session", sessionPath,
+			},
+		},
+		{
+			name: "remove mismatch",
+			args: []string{
+				"session", "locks", "remove", "2026-05-03", "narratio.transcript.final_trimmed",
+				"--session-id", "2026-05-04",
+				"--config", pipelinePath,
+				"--campaign-file", campaignPath,
+				"--session", sessionPath,
+			},
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var stdout bytes.Buffer
+			var stderr bytes.Buffer
+			code := Execute(tt.args, &stdout, &stderr)
+			if code == 0 {
+				t.Fatal("exit code = 0, want non-zero")
+			}
+			if !strings.Contains(stderr.String(), "does not match expected session id") {
+				t.Fatalf("stderr = %q, want session-id mismatch guidance", stderr.String())
+			}
+		})
+	}
+}
+
 func TestExecuteLocksCannotModifyStaticLocks(t *testing.T) {
 	workspaceRoot := t.TempDir()
 	pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot)
@@ -884,6 +931,31 @@ func TestExecuteStatusReportsMissingRemoteCurrentStateWithoutFailing(t *testing.
 	}
 }
 
+func TestExecuteStatusReportsPreviousStateReadinessWithoutFailing(t *testing.T) {
+	workspaceRoot := t.TempDir()
+	pipelinePath, campaignPath, sessionPath := writeValidConfigFilesWithScriptoriumArtifacts(t, workspaceRoot)
+	replaceInFileOrFatal(t, pipelinePath, "source: narratio.artifact.session_recap", "source: narratio.previous_session.artifact.session_recap")
+	replaceInFileOrFatal(t, sessionPath, "session_id: 2026-05-03\n", "session_id: 2026-05-03\nprevious_session_id: 2026-04-26\n")
+	fake := &storage.FakeBackend{}
+	var storeInitCalls int
+	restoreAppConfigTestGlobals(t, fake, &storeInitCalls, []string{sessionPath})
+
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	code := Execute([]string{
+		"session", "status", "2026-05-03",
+		"--config", pipelinePath,
+		"--campaign-file", campaignPath,
+		"--session", sessionPath,
+	}, &stdout, &stderr)
+	if code != 0 {
+		t.Fatalf("exit code = %d, want 0; stderr=%q", code, stderr.String())
+	}
+	if !strings.Contains(stdout.String(), "Previous-session artifacts: unavailable: remote current run pointer missing") {
+		t.Fatalf("stdout = %q, want previous readiness unavailable line", stdout.String())
+	}
+}
+
 func TestExecuteSessionValidateReportsPreviousStateFindingAndReturnsFindingError(t *testing.T) {
 	workspaceRoot := t.TempDir()
 	pipelinePath, campaignPath, sessionPath := writeValidConfigFilesWithScriptoriumArtifacts(t, workspaceRoot)

internal/app/operator_inspection.go

@@ -0,0 +1,274 @@
+package app
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/adapters/storage"
+	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
+	"gitea.maximumdirect.net/eric/narratio/internal/config"
+)
+
+type stableInputCheck struct {
+	Name string
+	Path string
+	Err  error
+}
+
+type localAudioCheck struct {
+	Checked bool
+	Paths   []string
+	Err     error
+}
+
+type remoteAudioCheck struct {
+	Checked bool
+	Prefix  string
+	Keys    []string
+	Err     error
+}
+
+type previousArtifactReadiness struct {
+	Requirements []artifacts.PreviousArtifactRequirement
+	MissingID    bool
+	Err          error
+}
+
+type remoteCurrentStateCheck struct {
+	State *RemoteCurrentState
+	Err   error
+}
+
+type effectiveLocksCheck struct {
+	Locks *effectiveLocks
+	Err   error
+}
+
+func inspectStableInputs(cfg *config.Config) []stableInputCheck {
+	items := []struct {
+		name string
+		in   config.ResolvedInputFile
+	}{
+		{name: "speakers", in: cfg.StableInputs.SpeakersFile},
+		{name: "autocorrect", in: cfg.StableInputs.AutocorrectFile},
+		{name: "glossary", in: cfg.StableInputs.GlossaryFile},
+	}
+	out := make([]stableInputCheck, 0, len(items))
+	for _, item := range items {
+		path, err := resolveHelperConfigRelativePath(item.in)
+		if err != nil {
+			out = append(out, stableInputCheck{Name: item.name, Err: err})
+			continue
+		}
+		if _, err := os.Stat(path); err != nil {
+			out = append(out, stableInputCheck{Name: item.name, Path: path, Err: err})
+			continue
+		}
+		out = append(out, stableInputCheck{Name: item.name, Path: path})
+	}
+	return out
+}
+
+func inspectLocalAudioPresence(cfg *config.Config) localAudioCheck {
+	if cfg.Session.Inputs.AudioS3 != nil {
+		return localAudioCheck{}
+	}
+
+	sessionDir := filepath.Dir(cfg.SessionPath)
+	resolved, err := resolveLocalInspectionAudioPaths(sessionDir, cfg.Session.Inputs)
+	if err != nil {
+		return localAudioCheck{Checked: true, Err: err}
+	}
+	return localAudioCheck{
+		Checked: true,
+		Paths:   resolved,
+	}
+}
+
+func inspectRemoteAudioPresence(ctx context.Context, cfg *config.Config, store storage.ObjectStore) remoteAudioCheck {
+	if cfg.Session.Inputs.AudioS3 == nil {
+		return remoteAudioCheck{}
+	}
+	if store == nil {
+		return remoteAudioCheck{Checked: true, Err: fmt.Errorf("storage backend is required for remote audio checks")}
+	}
+
+	sessionPrefix := artifacts.S3SessionPrefix(cfg.Pipeline.Storage.S3.RootPrefix, cfg.Session.Campaign, cfg.Session.SessionID)
+	audioPrefix := artifacts.S3AudioPrefix(sessionPrefix, cfg.Session.Inputs.AudioS3.Prefix)
+	objects, err := store.List(ctx, audioPrefix)
+	if err != nil {
+		return remoteAudioCheck{Checked: true, Prefix: audioPrefix, Err: err}
+	}
+
+	keys := make([]string, 0, len(objects))
+	seenBase := map[string]string{}
+	for _, obj := range objects {
+		key := strings.TrimSpace(obj.Key)
+		if key == "" || strings.HasSuffix(key, "/") || !isInspectionFlacPath(key) {
+			continue
+		}
+		base := path.Base(key)
+		if prev, exists := seenBase[base]; exists && prev != key {
+			return remoteAudioCheck{
+				Checked: true,
+				Prefix:  audioPrefix,
+				Err:     fmt.Errorf("duplicate s3 audio basename %q from %q and %q", base, prev, key),
+			}
+		}
+		seenBase[base] = key
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+	if len(keys) == 0 {
+		return remoteAudioCheck{
+			Checked: true,
+			Prefix:  audioPrefix,
+			Err:     fmt.Errorf("no .flac files found under s3 audio prefix %q", audioPrefix),
+		}
+	}
+	return remoteAudioCheck{
+		Checked: true,
+		Prefix:  audioPrefix,
+		Keys:    keys,
+	}
+}
+
+func inspectPreviousArtifactReadiness(
+	ctx context.Context,
+	cfg *config.Config,
+	store storage.ObjectStore,
+	requirements []artifacts.PreviousArtifactRequirement,
+) previousArtifactReadiness {
+	out := previousArtifactReadiness{
+		Requirements: append([]artifacts.PreviousArtifactRequirement(nil), requirements...),
+	}
+	if len(requirements) == 0 {
+		return out
+	}
+	if strings.TrimSpace(cfg.Session.PreviousSessionID) == "" {
+		out.MissingID = true
+		return out
+	}
+	if store == nil {
+		out.Err = fmt.Errorf("previous-session artifacts cannot be checked because storage is unavailable")
+		return out
+	}
+
+	prefix := artifacts.S3SessionPrefix(cfg.Pipeline.Storage.S3.RootPrefix, cfg.Session.Campaign, cfg.Session.PreviousSessionID)
+	if _, err := artifacts.LoadCurrentState(ctx, store, prefix, artifacts.CurrentStateValidation{
+		ExpectedSessionID: strings.TrimSpace(cfg.Session.PreviousSessionID),
+		ExpectedCampaign:  strings.TrimSpace(cfg.Session.Campaign),
+		ValidateRunID:     true,
+	}); err != nil {
+		out.Err = fmt.Errorf("remote %v", err)
+	}
+	return out
+}
+
+func inspectRemoteCurrentState(ctx context.Context, cfg *config.Config, store storage.ObjectStore) remoteCurrentStateCheck {
+	if store == nil {
+		return remoteCurrentStateCheck{}
+	}
+	current, err := discoverRemoteCurrentStateFn(ctx, cfg, store)
+	if err != nil {
+		return remoteCurrentStateCheck{Err: err}
+	}
+	return remoteCurrentStateCheck{State: current}
+}
+
+func inspectEffectiveLocks(ctx context.Context, cfg *config.Config, store storage.ObjectStore) effectiveLocksCheck {
+	locks, err := loadEffectiveLocks(ctx, cfg, store)
+	if err != nil {
+		return effectiveLocksCheck{Err: err}
+	}
+	return effectiveLocksCheck{Locks: locks}
+}
+
+func resolveLocalInspectionAudioPaths(sessionDir string, inputs config.SessionInputsConfig) ([]string, error) {
+	if len(inputs.AudioFiles) > 0 {
+		out := make([]string, 0, len(inputs.AudioFiles))
+		seenBase := map[string]string{}
+		for _, item := range inputs.AudioFiles {
+			resolved, err := resolveInspectionPath(sessionDir, item)
+			if err != nil {
+				return nil, err
+			}
+			if !isInspectionFlacPath(resolved) {
+				return nil, fmt.Errorf("audio file %q must have .flac extension", resolved)
+			}
+			if err := requireInspectionFile(resolved, "audio file"); err != nil {
+				return nil, err
+			}
+			base := filepath.Base(resolved)
+			if prev, exists := seenBase[base]; exists && prev != resolved {
+				return nil, fmt.Errorf("duplicate audio basename %q from %q and %q", base, prev, resolved)
+			}
+			seenBase[base] = resolved
+			out = append(out, resolved)
+		}
+		sort.Strings(out)
+		return out, nil
+	}
+
+	audioDir, err := resolveInspectionPath(sessionDir, inputs.AudioDir)
+	if err != nil {
+		return nil, err
+	}
+	entries, err := os.ReadDir(audioDir)
+	if err != nil {
+		return nil, fmt.Errorf("read audio directory %q: %w", audioDir, err)
+	}
+	out := make([]string, 0, len(entries))
+	for _, entry := range entries {
+		if entry.IsDir() {
+			continue
+		}
+		full := filepath.Join(audioDir, entry.Name())
+		if !isInspectionFlacPath(full) {
+			continue
+		}
+		if err := requireInspectionFile(full, "audio file"); err != nil {
+			return nil, err
+		}
+		out = append(out, full)
+	}
+	if len(out) == 0 {
+		return nil, fmt.Errorf("no .flac files found in audio directory %q", audioDir)
+	}
+	sort.Strings(out)
+	return out, nil
+}
+
+func resolveInspectionPath(baseDir, inputPath string) (string, error) {
+	pathValue := strings.TrimSpace(inputPath)
+	if pathValue == "" {
+		return "", fmt.Errorf("path is required")
+	}
+	if filepath.IsAbs(pathValue) {
+		return filepath.Clean(pathValue), nil
+	}
+	return filepath.Clean(filepath.Join(baseDir, pathValue)), nil
+}
+
+func requireInspectionFile(path, label string) error {
+	info, err := os.Stat(path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return fmt.Errorf("%s %q does not exist", label, path)
+		}
+		return fmt.Errorf("stat %s %q: %w", label, path, err)
+	}
+	if info.IsDir() {
+		return fmt.Errorf("%s %q is a directory", label, path)
+	}
+	return nil
+}
+
+func isInspectionFlacPath(path string) bool {
+	return strings.EqualFold(filepath.Ext(strings.TrimSpace(path)), ".flac")
+}

internal/app/operator_locks.go

@@ -48,13 +48,6 @@ func LocksList(ctx context.Context, args []string, out io.Writer) error {
 
 // LocksAdd adds or updates one remote lock.
 func LocksAdd(ctx context.Context, args []string, out io.Writer) error {
-	var positionalSessionID string
-	var source string
-	if len(args) >= 2 && !isCLIFlagToken(args[0]) && !isCLIFlagToken(args[1]) {
-		positionalSessionID = strings.TrimSpace(args[0])
-		source = strings.TrimSpace(args[1])
-		args = append([]string(nil), args[2:]...)
-	}
 	fs := flag.NewFlagSet("locks add", flag.ContinueOnError)
 	fs.SetOutput(io.Discard)
 	var flags commonConfigFlags
@@ -63,26 +56,8 @@ func LocksAdd(ctx context.Context, args []string, out io.Writer) error {
 	addCommonConfigFlags(fs, &flags)
 	fs.StringVar(&reason, "reason", "", "lock reason")
 	fs.BoolVar(&force, "force", false, "update existing remote lock")
-	if err := fs.Parse(args); err != nil {
-		return fmt.Errorf("locks add: invalid flags: %w", err)
-	}
-	if source == "" {
-		switch fs.NArg() {
-		case 2:
-			positionalSessionID = strings.TrimSpace(fs.Arg(0))
-			source = strings.TrimSpace(fs.Arg(1))
-		case 1:
-			if strings.TrimSpace(flags.sessionID) == "" {
-				return fmt.Errorf("locks add: expected session_id and source id")
-			}
-			source = strings.TrimSpace(fs.Arg(0))
-		default:
-			return fmt.Errorf("locks add: expected session_id and source id")
-		}
-	} else if fs.NArg() != 0 {
-		return fmt.Errorf("locks add: unexpected positional arguments")
-	}
-	if err := applyPositionalSessionID("locks add", positionalSessionID, &flags.sessionID); err != nil {
+	source, err := parseSessionIDAndOnePositionalArg("locks add", "source id", fs, args, &flags.sessionID)
+	if err != nil {
 		return err
 	}
 	if strings.TrimSpace(flags.sessionID) == "" {
@@ -116,37 +91,12 @@ func LocksAdd(ctx context.Context, args []string, out io.Writer) error {
 
 // LocksRemove removes one remote lock.
 func LocksRemove(ctx context.Context, args []string, out io.Writer) error {
-	var positionalSessionID string
-	var source string
-	if len(args) >= 2 && !isCLIFlagToken(args[0]) && !isCLIFlagToken(args[1]) {
-		positionalSessionID = strings.TrimSpace(args[0])
-		source = strings.TrimSpace(args[1])
-		args = append([]string(nil), args[2:]...)
-	}
 	fs := flag.NewFlagSet("locks remove", flag.ContinueOnError)
 	fs.SetOutput(io.Discard)
 	var flags commonConfigFlags
 	addCommonConfigFlags(fs, &flags)
-	if err := fs.Parse(args); err != nil {
-		return fmt.Errorf("locks remove: invalid flags: %w", err)
-	}
-	if source == "" {
-		switch fs.NArg() {
-		case 2:
-			positionalSessionID = strings.TrimSpace(fs.Arg(0))
-			source = strings.TrimSpace(fs.Arg(1))
-		case 1:
-			if strings.TrimSpace(flags.sessionID) == "" {
-				return fmt.Errorf("locks remove: expected session_id and source id")
-			}
-			source = strings.TrimSpace(fs.Arg(0))
-		default:
-			return fmt.Errorf("locks remove: expected session_id and source id")
-		}
-	} else if fs.NArg() != 0 {
-		return fmt.Errorf("locks remove: unexpected positional arguments")
-	}
-	if err := applyPositionalSessionID("locks remove", positionalSessionID, &flags.sessionID); err != nil {
+	source, err := parseSessionIDAndOnePositionalArg("locks remove", "source id", fs, args, &flags.sessionID)
+	if err != nil {
 		return err
 	}
 	if strings.TrimSpace(flags.sessionID) == "" {

internal/app/operator_session_validate.go

@@ -54,23 +54,26 @@ func SessionValidate(ctx context.Context, args []string, out io.Writer) error {
 	}
 
 	requirements := artifacts.CollectPreviousArtifactRequirements(configuredScriptoriumArtifacts(cfg))
-	if len(requirements) == 0 {
+	previous := inspectPreviousArtifactReadiness(ctx, cfg, store, requirements)
+	if len(previous.Requirements) == 0 {
 		findings = append(findings, okFinding("previous", "no previous-session artifacts required"))
-	} else if strings.TrimSpace(cfg.Session.PreviousSessionID) == "" {
+	} else if previous.MissingID {
 		findings = append(findings, errorFinding("previous", "previous_session_id is required by configured previous-session artifacts"))
-	} else if storeErr != nil {
-		findings = append(findings, errorFinding("previous", "previous-session artifacts cannot be checked because storage is unavailable"))
+	} else if previous.Err != nil {
+		findings = append(findings, errorFinding("previous", previous.Err.Error()))
 	} else {
-		findings = append(findings, validatePreviousArtifactFindings(ctx, cfg, store, requirements)...)
+		for _, req := range previous.Requirements {
+			findings = append(findings, okFinding("previous", fmt.Sprintf("%s required=%t", req.Name, req.Required)))
+		}
 	}
 
-	locks, lockErr := loadEffectiveLocks(ctx, cfg, store)
-	if lockErr != nil {
-		findings = append(findings, errorFinding("locks", lockErr.Error()))
-	} else if len(locks.All) == 0 {
+	locks := inspectEffectiveLocks(ctx, cfg, store)
+	if locks.Err != nil {
+		findings = append(findings, errorFinding("locks", locks.Err.Error()))
+	} else if len(locks.Locks.All) == 0 {
 		findings = append(findings, okFinding("locks", "no effective publish locks"))
 	} else {
-		for _, lock := range locks.All {
+		for _, lock := range locks.Locks.All {
 			findings = append(findings, warnFinding("locks", fmt.Sprintf("%s locked: %s", lock.Source, strings.TrimSpace(lock.Reason))))
 		}
 	}

internal/app/operator_status.go

@@ -5,8 +5,10 @@ import (
 	"flag"
 	"fmt"
 	"io"
+	"sort"
 	"strings"
 
+	"gitea.maximumdirect.net/eric/narratio/internal/adapters/storage"
 	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
 	"gitea.maximumdirect.net/eric/narratio/internal/config"
 )
@@ -35,6 +37,8 @@ func Status(ctx context.Context, args []string, out io.Writer) error {
 	fmt.Fprintf(out, "Campaign: %s\n", cfg.Session.Campaign)
 	fmt.Fprintf(out, "Workspace: %s\n", paths.Root)
 	fmt.Fprintf(out, "Session config: %s\n", sessionSourceSummary(cfg))
+	writeStatusStableInputs(out, inspectStableInputs(cfg))
+	writeStatusLocalAudio(out, inspectLocalAudioPresence(cfg))
 
 	if m, err := loadLocalManifest(ctx, paths.ManifestPath); err != nil {
 		fmt.Fprintf(out, "Local manifest: error: %v\n", err)
@@ -49,21 +53,30 @@ func Status(ctx context.Context, args []string, out io.Writer) error {
 	if storeErr != nil {
 		fmt.Fprintf(out, "Remote publish: unavailable: %v\n", storeErr)
 	} else if store != nil {
-		current, err := discoverRemoteCurrentStateFn(ctx, cfg, store)
-		if err != nil {
-			fmt.Fprintf(out, "Remote publish: missing or unavailable: %v\n", err)
+		current := inspectRemoteCurrentState(ctx, cfg, store)
+		if current.Err != nil {
+			fmt.Fprintf(out, "Remote publish: missing or unavailable: %v\n", current.Err)
 		} else {
-			fmt.Fprintf(out, "Remote publish: current run %s\n", current.RunID)
-			fmt.Fprintf(out, "Remote manifest: %s\n", current.CurrentManifestKey)
+			fmt.Fprintf(out, "Remote publish: current run %s\n", current.State.RunID)
+			fmt.Fprintf(out, "Remote manifest: %s\n", current.State.CurrentManifestKey)
 		}
 	}
+	writeStatusRemoteAudio(ctx, out, cfg, store, storeErr)
+	writeStatusPreviousArtifacts(out, inspectPreviousArtifactReadiness(
+		ctx,
+		cfg,
+		store,
+		artifacts.CollectPreviousArtifactRequirements(configuredScriptoriumArtifacts(cfg)),
+	))
 
-	locks, err := loadEffectiveLocks(ctx, cfg, store)
+	lockChecks := inspectEffectiveLocks(ctx, cfg, store)
+	locks := lockChecks.Locks
+	lockErr := lockChecks.Err
 	if catalog, catalogErr := buildHelperArtifactCatalog(cfg); catalogErr != nil {
 		fmt.Fprintf(out, "Remote outputs: error: %v\n", catalogErr)
 	} else if storeErr == nil {
 		catalogLocks := locks
-		if err != nil {
+		if lockErr != nil {
 			catalogLocks = &effectiveLocks{
 				Static: staticPublishLocks(cfg),
 				All:    staticPublishLocks(cfg),
@@ -76,8 +89,8 @@ func Status(ctx context.Context, args []string, out io.Writer) error {
 		fmt.Fprintln(out, "Remote outputs:")
 		writeArtifactList(out, cfg, catalog, catalogLocks, publishedRemoteState)
 	}
-	if err != nil {
-		fmt.Fprintf(out, "Publish locks: error: %v\n", err)
+	if lockErr != nil {
+		fmt.Fprintf(out, "Publish locks: error: %v\n", lockErr)
 	} else {
 		writeLocks(out, cfg, locks)
 	}
@@ -86,3 +99,68 @@ func Status(ctx context.Context, args []string, out io.Writer) error {
 	fmt.Fprintf(out, "- narratio session restore %s --dry-run\n", cfg.Session.SessionID)
 	return nil
 }
+
+func writeStatusStableInputs(out io.Writer, checks []stableInputCheck) {
+	if len(checks) == 0 {
+		return
+	}
+	for _, check := range checks {
+		if check.Err != nil {
+			if strings.TrimSpace(check.Path) != "" {
+				fmt.Fprintf(out, "Stable input %s: unavailable: %v\n", check.Name, check.Err)
+			} else {
+				fmt.Fprintf(out, "Stable input %s: unavailable: %s\n", check.Name, check.Err.Error())
+			}
+			continue
+		}
+		fmt.Fprintf(out, "Stable input %s: %s\n", check.Name, check.Path)
+	}
+}
+
+func writeStatusLocalAudio(out io.Writer, check localAudioCheck) {
+	if !check.Checked {
+		return
+	}
+	if check.Err != nil {
+		fmt.Fprintf(out, "Local audio: unavailable: %v\n", check.Err)
+		return
+	}
+	fmt.Fprintf(out, "Local audio: %d file(s)\n", len(check.Paths))
+}
+
+func writeStatusRemoteAudio(ctx context.Context, out io.Writer, cfg *config.Config, store storage.ObjectStore, storeErr error) {
+	if cfg.Session.Inputs.AudioS3 == nil {
+		return
+	}
+	if storeErr != nil {
+		fmt.Fprintf(out, "Remote audio: unavailable: %v\n", storeErr)
+		return
+	}
+	check := inspectRemoteAudioPresence(ctx, cfg, store)
+	if check.Err != nil {
+		fmt.Fprintf(out, "Remote audio: unavailable: %v\n", check.Err)
+		return
+	}
+	fmt.Fprintf(out, "Remote audio: %d .flac object(s)\n", len(check.Keys))
+}
+
+func writeStatusPreviousArtifacts(out io.Writer, readiness previousArtifactReadiness) {
+	if len(readiness.Requirements) == 0 {
+		fmt.Fprintln(out, "Previous-session artifacts: not required")
+		return
+	}
+	if readiness.MissingID {
+		fmt.Fprintln(out, "Previous-session artifacts: unavailable: previous_session_id is required by configured previous-session artifacts")
+		return
+	}
+	if readiness.Err != nil {
+		fmt.Fprintf(out, "Previous-session artifacts: unavailable: %v\n", readiness.Err)
+		return
+	}
+	names := make([]string, 0, len(readiness.Requirements))
+	for _, req := range readiness.Requirements {
+		names = append(names, fmt.Sprintf("%s(required=%t)", req.Name, req.Required))
+	}
+	sort.Strings(names)
+	fmt.Fprintf(out, "Previous-session artifacts: ready: %s\n", strings.Join(names, ", "))
+}

internal/app/restore_execute.go

@@ -11,6 +11,7 @@ import (
 	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
 	"gitea.maximumdirect.net/eric/narratio/internal/audio"
 	"gitea.maximumdirect.net/eric/narratio/internal/config"
+	"gitea.maximumdirect.net/eric/narratio/internal/fileops"
 	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
 )
 
@@ -114,10 +115,7 @@ func executeRestoreDownloadAction(
 		}
 	}
 
-	if err := os.Chmod(tmpPath, 0o644); err != nil {
-		return fmt.Errorf("set file permissions: %w", err)
-	}
-	if err := os.Rename(tmpPath, safeLocalPath); err != nil {
+	if err := fileops.InstallDownloadedTempFile(tmpPath, safeLocalPath, 0o644); err != nil {
 		return fmt.Errorf("install file atomically: %w", err)
 	}
 	removeTmp = false

internal/app/restore_plan.go

@@ -2,6 +2,7 @@ package app
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"io"
 	"os"
@@ -13,6 +14,7 @@ import (
 	"gitea.maximumdirect.net/eric/narratio/internal/adapters/storage"
 	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
 	"gitea.maximumdirect.net/eric/narratio/internal/config"
+	"gitea.maximumdirect.net/eric/narratio/internal/pathsafe"
 	"gitea.maximumdirect.net/eric/narratio/internal/previouscache"
 )
 
@@ -215,19 +217,17 @@ func joinWithinSessionRoot(sessionRoot, relative string) (string, error) {
 	if strings.TrimSpace(sessionRoot) == "" {
 		return "", fmt.Errorf("session root is required")
 	}
-	cleanRel := path.Clean(strings.TrimSpace(relative))
-	if cleanRel == "." || cleanRel == "" {
+	joined, err := pathsafe.JoinSlashRelativeUnderRoot(sessionRoot, filepath.ToSlash(strings.TrimSpace(relative)))
+	if err != nil {
+		if errors.Is(err, pathsafe.ErrRelativePathRequired) {
 			return "", fmt.Errorf("relative path is required")
 		}
-	if cleanRel == ".." || strings.HasPrefix(cleanRel, "../") || strings.HasPrefix(cleanRel, "/") {
+		if errors.Is(err, pathsafe.ErrRelativePathEscape) || errors.Is(err, pathsafe.ErrRelativePathAbsolute) {
 			return "", fmt.Errorf("relative path escapes session root")
 		}
-	abs := filepath.Clean(filepath.Join(sessionRoot, filepath.FromSlash(cleanRel)))
-	root := filepath.Clean(sessionRoot)
-	if abs != root && !strings.HasPrefix(abs, root+string(filepath.Separator)) {
-		return "", fmt.Errorf("resolved local path escapes session root")
+		return "", fmt.Errorf("join relative path under session root: %w", err)
 	}
-	return abs, nil
+	return joined, nil
 }
 
 func buildPreviousCacheRestoreActions(

internal/app/session_args.go

@@ -59,3 +59,37 @@ func parseSessionAwareFlags(command string, fs *flag.FlagSet, args []string, ses
 	}
 	return resolveParsedSessionID(command, positionalSessionID, fs, sessionID)
 }
+
+func parseSessionIDAndOnePositionalArg(command, argName string, fs *flag.FlagSet, args []string, sessionID *string) (string, error) {
+	var positionalSessionID string
+	value := ""
+	if len(args) >= 2 && !isCLIFlagToken(args[0]) && !isCLIFlagToken(args[1]) {
+		positionalSessionID = strings.TrimSpace(args[0])
+		value = strings.TrimSpace(args[1])
+		args = append([]string(nil), args[2:]...)
+	}
+
+	if err := fs.Parse(args); err != nil {
+		return "", fmt.Errorf("%s: invalid flags: %w", command, err)
+	}
+	if value == "" {
+		switch fs.NArg() {
+		case 2:
+			positionalSessionID = strings.TrimSpace(fs.Arg(0))
+			value = strings.TrimSpace(fs.Arg(1))
+		case 1:
+			if strings.TrimSpace(*sessionID) == "" {
+				return "", fmt.Errorf("%s: expected session_id and %s", command, argName)
+			}
+			value = strings.TrimSpace(fs.Arg(0))
+		default:
+			return "", fmt.Errorf("%s: expected session_id and %s", command, argName)
+		}
+	} else if fs.NArg() != 0 {
+		return "", fmt.Errorf("%s: unexpected positional arguments", command)
+	}
+	if err := applyPositionalSessionID(command, positionalSessionID, sessionID); err != nil {
+		return "", err
+	}
+	return value, nil
+}

internal/artifactpolicy/policy.go

@@ -1,6 +1,7 @@
 package artifactpolicy
 
 import (
+	"errors"
 	"fmt"
 	"regexp"
 	"strings"
@@ -19,6 +20,11 @@ const (
 var configuredSourceRE = regexp.MustCompile(`^narratio\.artifact\.([a-z][a-z0-9_]*)$`)
 var previousSourceRE = regexp.MustCompile(`^narratio\.previous_session\.artifact\.([a-z][a-z0-9_]*)$`)
 
+var (
+	ErrUnsupportedScriptoriumInputSource = errors.New("unsupported scriptorium input source")
+	ErrInvalidPreviousSessionSource      = errors.New("invalid previous-session source format")
+)
+
 type SourceKind string
 
 const (
@@ -34,6 +40,28 @@ type Source struct {
 	ConfiguredKey string
 }
 
+// ScriptoriumInputSourceDescriptor describes one validated Scriptorium input source.
+type ScriptoriumInputSourceDescriptor struct {
+	Source          Source
+	PreviousSession *PreviousSessionSourceDescriptor
+}
+
+// PreviousSessionSourceDescriptor describes one canonical previous-session input source.
+type PreviousSessionSourceDescriptor struct {
+	SourceID           string
+	ConfiguredKey      string
+	ConfiguredSourceID string
+}
+
+// UnknownConfiguredArtifactError reports a source that references an undefined configured artifact key.
+type UnknownConfiguredArtifactError struct {
+	ConfiguredKey string
+}
+
+func (e *UnknownConfiguredArtifactError) Error() string {
+	return fmt.Sprintf("references unknown artifact %q", e.ConfiguredKey)
+}
+
 // ConfiguredSourceID converts a configured artifact key into source id form.
 func ConfiguredSourceID(key string) string {
 	return configuredSourcePrefix + strings.TrimSpace(key)
@@ -83,6 +111,70 @@ func ClassifySource(source string) (Source, error) {
 	return Source{}, fmt.Errorf("unsupported artifact source %q", source)
 }
 
+// DescribeScriptoriumInputSource classifies one input source and returns descriptor
+// metadata used by config validation, analyze input resolution, and previous-cache planning.
+func DescribeScriptoriumInputSource(source string) (ScriptoriumInputSourceDescriptor, error) {
+	trimmed := strings.TrimSpace(source)
+	if trimmed == "" {
+		return ScriptoriumInputSourceDescriptor{}, ErrUnsupportedScriptoriumInputSource
+	}
+	if strings.HasPrefix(trimmed, "narratio.previous_session.artifact") {
+		descriptor, err := DescribePreviousSessionSource(trimmed)
+		if err != nil {
+			return ScriptoriumInputSourceDescriptor{}, err
+		}
+		return ScriptoriumInputSourceDescriptor{
+			Source: Source{
+				ID:            descriptor.SourceID,
+				Kind:          SourceKindPreviousArtifact,
+				ConfiguredKey: descriptor.ConfiguredKey,
+			},
+			PreviousSession: &descriptor,
+		}, nil
+	}
+
+	classified, err := ClassifySource(trimmed)
+	if err != nil {
+		return ScriptoriumInputSourceDescriptor{}, ErrUnsupportedScriptoriumInputSource
+	}
+	return ScriptoriumInputSourceDescriptor{Source: classified}, nil
+}
+
+// DescribePreviousSessionSource validates a canonical previous-session source id
+// and returns both previous and configured-source vocabulary descriptors.
+func DescribePreviousSessionSource(source string) (PreviousSessionSourceDescriptor, error) {
+	configuredKey, ok := ParsePreviousSessionSource(source)
+	if !ok {
+		return PreviousSessionSourceDescriptor{}, ErrInvalidPreviousSessionSource
+	}
+	return PreviousSessionSourceDescriptor{
+		SourceID:           PreviousSessionSourceID(configuredKey),
+		ConfiguredKey:      configuredKey,
+		ConfiguredSourceID: ConfiguredSourceID(configuredKey),
+	}, nil
+}
+
+// PreviousSessionSourceDescriptorForConfiguredKey derives a previous-session source descriptor
+// from a configured artifact key.
+func PreviousSessionSourceDescriptorForConfiguredKey(configuredKey string) (PreviousSessionSourceDescriptor, error) {
+	return DescribePreviousSessionSource(PreviousSessionSourceID(configuredKey))
+}
+
+// ValidateInputConfiguredReference checks that configured/previous-session sources
+// reference configured artifacts known to the current Scriptorium config.
+func ValidateInputConfiguredReference(
+	descriptor ScriptoriumInputSourceDescriptor,
+	configured map[string]struct{},
+) error {
+	switch descriptor.Source.Kind {
+	case SourceKindConfiguredArtifact, SourceKindPreviousArtifact:
+		if _, ok := configured[descriptor.Source.ConfiguredKey]; !ok {
+			return &UnknownConfiguredArtifactError{ConfiguredKey: descriptor.Source.ConfiguredKey}
+		}
+	}
+	return nil
+}
+
 // ValidatePublishSource validates that a source is publish-compatible and references a known configured artifact.
 func ValidatePublishSource(source string, configured map[string]string) (Source, error) {
 	classified, err := ClassifySource(source)

internal/artifactpolicy/policy_test.go

@@ -1,6 +1,7 @@
 package artifactpolicy
 
 import (
+	"errors"
 	"strings"
 	"testing"
 )
@@ -90,3 +91,101 @@ func TestResolvePublishedDestinationRejectsTraversal(t *testing.T) {
 		t.Fatal("ResolvePublishedDestination() error = nil, want traversal rejection")
 	}
 }
+
+func TestDescribeScriptoriumInputSource(t *testing.T) {
+	tests := []struct {
+		name        string
+		source      string
+		wantKind    SourceKind
+		wantKey     string
+		wantPrev    bool
+		wantErr     error
+		wantErrLike string
+	}{
+		{name: "built in", source: "narratio.transcript.final_trimmed", wantKind: SourceKindBuiltIn},
+		{name: "configured", source: "narratio.artifact.session_recap", wantKind: SourceKindConfiguredArtifact, wantKey: "session_recap"},
+		{name: "previous", source: "narratio.previous_session.artifact.session_recap", wantKind: SourceKindPreviousArtifact, wantKey: "session_recap", wantPrev: true},
+		{name: "invalid previous", source: "narratio.previous_session.artifact.", wantErr: ErrInvalidPreviousSessionSource},
+		{name: "unsupported", source: "narratio.unknown", wantErr: ErrUnsupportedScriptoriumInputSource},
+		{name: "empty", source: " ", wantErr: ErrUnsupportedScriptoriumInputSource},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := DescribeScriptoriumInputSource(tt.source)
+			if tt.wantErr != nil {
+				if !errors.Is(err, tt.wantErr) {
+					t.Fatalf("DescribeScriptoriumInputSource() error = %v, want %v", err, tt.wantErr)
+				}
+				return
+			}
+			if tt.wantErrLike != "" {
+				if err == nil || !strings.Contains(err.Error(), tt.wantErrLike) {
+					t.Fatalf("DescribeScriptoriumInputSource() error = %v, want like %q", err, tt.wantErrLike)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("DescribeScriptoriumInputSource() error = %v", err)
+			}
+			if got.Source.Kind != tt.wantKind {
+				t.Fatalf("DescribeScriptoriumInputSource().Source.Kind = %q, want %q", got.Source.Kind, tt.wantKind)
+			}
+			if got.Source.ConfiguredKey != tt.wantKey {
+				t.Fatalf("DescribeScriptoriumInputSource().Source.ConfiguredKey = %q, want %q", got.Source.ConfiguredKey, tt.wantKey)
+			}
+			if tt.wantPrev && got.PreviousSession == nil {
+				t.Fatal("DescribeScriptoriumInputSource().PreviousSession = nil, want descriptor")
+			}
+			if !tt.wantPrev && got.PreviousSession != nil {
+				t.Fatalf("DescribeScriptoriumInputSource().PreviousSession = %#v, want nil", got.PreviousSession)
+			}
+		})
+	}
+}
+
+func TestValidateInputConfiguredReference(t *testing.T) {
+	configured := map[string]struct{}{"session_recap": {}}
+
+	desc, err := DescribeScriptoriumInputSource("narratio.artifact.session_recap")
+	if err != nil {
+		t.Fatalf("DescribeScriptoriumInputSource(configured) error = %v", err)
+	}
+	if err := ValidateInputConfiguredReference(desc, configured); err != nil {
+		t.Fatalf("ValidateInputConfiguredReference(configured) error = %v", err)
+	}
+
+	prevDesc, err := DescribeScriptoriumInputSource("narratio.previous_session.artifact.session_recap")
+	if err != nil {
+		t.Fatalf("DescribeScriptoriumInputSource(previous) error = %v", err)
+	}
+	if err := ValidateInputConfiguredReference(prevDesc, configured); err != nil {
+		t.Fatalf("ValidateInputConfiguredReference(previous) error = %v", err)
+	}
+
+	missingDesc, err := DescribeScriptoriumInputSource("narratio.artifact.quest_log")
+	if err != nil {
+		t.Fatalf("DescribeScriptoriumInputSource(missing configured) error = %v", err)
+	}
+	err = ValidateInputConfiguredReference(missingDesc, configured)
+	var unknown *UnknownConfiguredArtifactError
+	if !errors.As(err, &unknown) || unknown.ConfiguredKey != "quest_log" {
+		t.Fatalf("ValidateInputConfiguredReference(missing configured) error = %v, want UnknownConfiguredArtifactError(quest_log)", err)
+	}
+}
+
+func TestPreviousSessionSourceDescriptorForConfiguredKey(t *testing.T) {
+	got, err := PreviousSessionSourceDescriptorForConfiguredKey("session_recap")
+	if err != nil {
+		t.Fatalf("PreviousSessionSourceDescriptorForConfiguredKey() error = %v", err)
+	}
+	if got.SourceID != "narratio.previous_session.artifact.session_recap" {
+		t.Fatalf("SourceID = %q, want narratio.previous_session.artifact.session_recap", got.SourceID)
+	}
+	if got.ConfiguredSourceID != "narratio.artifact.session_recap" {
+		t.Fatalf("ConfiguredSourceID = %q, want narratio.artifact.session_recap", got.ConfiguredSourceID)
+	}
+	if got.ConfiguredKey != "session_recap" {
+		t.Fatalf("ConfiguredKey = %q, want session_recap", got.ConfiguredKey)
+	}
+}

internal/artifacts/local.go

@@ -9,6 +9,9 @@ import (
 	"strconv"
 	"strings"
 	"time"
+
+	"gitea.maximumdirect.net/eric/narratio/internal/fileops"
+	"gitea.maximumdirect.net/eric/narratio/internal/pathsafe"
 )
 
 // ErrLockConflict is returned when a session lock already exists.
@@ -101,7 +104,7 @@ func (s *LocalStore) copyInputWithPaths(paths SessionPaths, sessionID, srcPath,
 		return Ref{}, fmt.Errorf("copy input: %w", err)
 	}
 
-	if err := copyFileAtomic(srcPath, destAbs, 0o644); err != nil {
+	if err := fileops.CopyFileAtomic(srcPath, destAbs, 0o644); err != nil {
 		return Ref{}, fmt.Errorf("copy input %q -> %q: %w", srcPath, destAbs, err)
 	}
 
@@ -145,45 +148,9 @@ func (s *LocalStore) WriteFileAtomic(path string, data []byte, perm os.FileMode)
 	if strings.TrimSpace(path) == "" {
 		return fmt.Errorf("write file atomic: path is required")
 	}
-
-	dir := filepath.Dir(path)
-	if err := os.MkdirAll(dir, 0o755); err != nil {
-		return fmt.Errorf("write file atomic: create parent dir %q: %w", dir, err)
+	if err := fileops.WriteFileAtomic(path, data, perm); err != nil {
+		return fmt.Errorf("write file atomic: %w", err)
 	}
-
-	base := filepath.Base(path)
-	tmp, err := os.CreateTemp(dir, "."+base+".tmp-*")
-	if err != nil {
-		return fmt.Errorf("write file atomic: create temp file: %w", err)
-	}
-	tmpName := tmp.Name()
-	removeTmp := true
-	defer func() {
-		if removeTmp {
-			_ = os.Remove(tmpName)
-		}
-	}()
-
-	if _, err := tmp.Write(data); err != nil {
-		_ = tmp.Close()
-		return fmt.Errorf("write file atomic: write temp file: %w", err)
-	}
-	if err := tmp.Sync(); err != nil {
-		_ = tmp.Close()
-		return fmt.Errorf("write file atomic: sync temp file: %w", err)
-	}
-	if err := tmp.Close(); err != nil {
-		return fmt.Errorf("write file atomic: close temp file: %w", err)
-	}
-
-	if err := os.Chmod(tmpName, perm); err != nil {
-		return fmt.Errorf("write file atomic: chmod temp file: %w", err)
-	}
-	if err := os.Rename(tmpName, path); err != nil {
-		return fmt.Errorf("write file atomic: rename temp file: %w", err)
-	}
-	removeTmp = false
-
 	return nil
 }
 
@@ -256,62 +223,21 @@ func (s *LocalStore) ReleaseSessionLock(lock *LockHandle) error {
 }
 
 func resolveInRoot(root, relative string) (string, error) {
-	rel := filepath.Clean(relative)
-	if rel == "." || rel == "" {
+	joined, err := pathsafe.JoinSlashRelativeUnderRoot(root, filepath.ToSlash(relative))
+	if err != nil {
+		switch {
+		case errors.Is(err, pathsafe.ErrRelativePathRequired):
+			return "", fmt.Errorf("relative destination path is required")
+		case errors.Is(err, pathsafe.ErrRelativePathAbsolute):
+			return "", fmt.Errorf("relative destination must not be absolute: %q", relative)
+		case errors.Is(err, pathsafe.ErrRelativePathEscape):
+			return "", fmt.Errorf("relative destination escapes root: %q", relative)
+		default:
+			return "", fmt.Errorf("resolve destination in root: %w", err)
+		}
+	}
+	if strings.TrimSpace(joined) == "" {
 		return "", fmt.Errorf("relative destination path is required")
 	}
-	if filepath.IsAbs(rel) {
-		return "", fmt.Errorf("relative destination must not be absolute: %q", relative)
-	}
-	if rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
-		return "", fmt.Errorf("relative destination escapes root: %q", relative)
-	}
-	return filepath.Join(root, rel), nil
-}
-
-func copyFileAtomic(srcPath, dstPath string, perm os.FileMode) error {
-	src, err := os.Open(srcPath)
-	if err != nil {
-		return err
-	}
-	defer src.Close()
-
-	if err := os.MkdirAll(filepath.Dir(dstPath), 0o755); err != nil {
-		return err
-	}
-
-	dir := filepath.Dir(dstPath)
-	base := filepath.Base(dstPath)
-	tmp, err := os.CreateTemp(dir, "."+base+".tmp-*")
-	if err != nil {
-		return err
-	}
-	tmpName := tmp.Name()
-	removeTmp := true
-	defer func() {
-		if removeTmp {
-			_ = os.Remove(tmpName)
-		}
-	}()
-
-	if _, err := io.Copy(tmp, src); err != nil {
-		_ = tmp.Close()
-		return err
-	}
-	if err := tmp.Sync(); err != nil {
-		_ = tmp.Close()
-		return err
-	}
-	if err := tmp.Close(); err != nil {
-		return err
-	}
-	if err := os.Chmod(tmpName, perm); err != nil {
-		return err
-	}
-	if err := os.Rename(tmpName, dstPath); err != nil {
-		return err
-	}
-	removeTmp = false
-
-	return nil
+	return joined, nil
 }

internal/artifacts/previous_requirements.go

@@ -5,6 +5,7 @@ import (
 	"sort"
 	"strings"
 
+	"gitea.maximumdirect.net/eric/narratio/internal/artifactpolicy"
 	"gitea.maximumdirect.net/eric/narratio/internal/config"
 )
 
@@ -36,10 +37,11 @@ func CollectPreviousArtifactRequirements(
 		inputNames := sortedScriptoriumInputKeys(artifactCfg.Inputs)
 		for _, inputName := range inputNames {
 			inputCfg := artifactCfg.Inputs[inputName]
-			previousName, ok := PreviousSessionArtifactName(inputCfg.Source)
-			if !ok {
+			descriptor, err := artifactpolicy.DescribeScriptoriumInputSource(inputCfg.Source)
+			if err != nil || descriptor.PreviousSession == nil {
 				continue
 			}
+			previousName := descriptor.PreviousSession.ConfiguredKey
 
 			location := fmt.Sprintf(
 				"pipeline.scriptorium.artifacts.%s.inputs.%s.source",

internal/audio/s3_audio.go

@@ -2,16 +2,14 @@ package audio
 
 import (
 	"context"
-	"crypto/sha256"
-	"encoding/hex"
 	"fmt"
-	"io"
 	"os"
 	"path/filepath"
 	"strings"
 
 	"gitea.maximumdirect.net/eric/narratio/internal/adapters/storage"
 	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
+	"gitea.maximumdirect.net/eric/narratio/internal/fileops"
 )
 
 // S3MaterializeRequest describes one S3-backed audio materialization.
@@ -61,7 +59,7 @@ func MaterializeS3Audio(ctx context.Context, req S3MaterializeRequest) (S3Materi
 		if ok, err := validCachedAudio(cachePath, req.Object.Size); err != nil {
 			return S3MaterializeResult{}, err
 		} else if ok {
-			checksum, err := copyFileAtomicWithChecksum(cachePath, req.DestPath, 0o644)
+			checksum, err := fileops.CopyFileAtomicWithChecksum(cachePath, req.DestPath, 0o644)
 			if err != nil {
 				return S3MaterializeResult{}, fmt.Errorf("materialize cached audio %q: %w", cachePath, err)
 			}
@@ -82,7 +80,7 @@ func MaterializeS3Audio(ctx context.Context, req S3MaterializeRequest) (S3Materi
 		return S3MaterializeResult{}, fmt.Errorf("validate downloaded audio %q: %w", spoolPath, err)
 	}
 
-	checksum, err := copyFileAtomicWithChecksum(spoolPath, req.DestPath, 0o644)
+	checksum, err := fileops.CopyFileAtomicWithChecksum(spoolPath, req.DestPath, 0o644)
 	if err != nil {
 		return S3MaterializeResult{}, fmt.Errorf("materialize downloaded audio %q: %w", filepath.Base(req.DestPath), err)
 	}
@@ -91,7 +89,7 @@ func MaterializeS3Audio(ctx context.Context, req S3MaterializeRequest) (S3Materi
 	result.Downloaded = true
 
 	if result.CachePath != "" {
-		if _, err := copyFileAtomicWithChecksum(spoolPath, result.CachePath, 0o644); err != nil {
+		if _, err := fileops.CopyFileAtomicWithChecksum(spoolPath, result.CachePath, 0o644); err != nil {
 			return S3MaterializeResult{}, fmt.Errorf("populate audio cache %q: %w", result.CachePath, err)
 		}
 	}
@@ -164,60 +162,9 @@ func downloadObjectAtomic(ctx context.Context, store storage.ObjectStore, key, d
 	if err := store.Download(ctx, key, tmpPath); err != nil {
 		return err
 	}
-	if err := os.Chmod(tmpPath, 0o644); err != nil {
-		return fmt.Errorf("set temp file permissions: %w", err)
-	}
-	if err := os.Rename(tmpPath, destPath); err != nil {
-		return fmt.Errorf("install downloaded file: %w", err)
+	if err := fileops.InstallDownloadedTempFile(tmpPath, destPath, 0o644); err != nil {
+		return err
 	}
 	removeTmp = false
 	return nil
 }
-
-func copyFileAtomicWithChecksum(src, dst string, perm os.FileMode) (string, error) {
-	if strings.TrimSpace(src) == "" || strings.TrimSpace(dst) == "" {
-		return "", fmt.Errorf("source and destination paths are required")
-	}
-	in, err := os.Open(src)
-	if err != nil {
-		return "", err
-	}
-	defer func() { _ = in.Close() }()
-
-	if err := os.MkdirAll(filepath.Dir(dst), 0o755); err != nil {
-		return "", fmt.Errorf("create destination directory: %w", err)
-	}
-	base := filepath.Base(dst)
-	tmp, err := os.CreateTemp(filepath.Dir(dst), "."+base+".tmp-*")
-	if err != nil {
-		return "", fmt.Errorf("create temp file: %w", err)
-	}
-	tmpPath := tmp.Name()
-	removeTmp := true
-	defer func() {
-		if removeTmp {
-			_ = os.Remove(tmpPath)
-		}
-	}()
-
-	digest := sha256.New()
-	if _, err := io.Copy(io.MultiWriter(tmp, digest), in); err != nil {
-		_ = tmp.Close()
-		return "", fmt.Errorf("copy file: %w", err)
-	}
-	if err := tmp.Sync(); err != nil {
-		_ = tmp.Close()
-		return "", fmt.Errorf("sync temp file: %w", err)
-	}
-	if err := tmp.Close(); err != nil {
-		return "", fmt.Errorf("close temp file: %w", err)
-	}
-	if err := os.Chmod(tmpPath, perm); err != nil {
-		return "", fmt.Errorf("chmod temp file: %w", err)
-	}
-	if err := os.Rename(tmpPath, dst); err != nil {
-		return "", fmt.Errorf("install temp file: %w", err)
-	}
-	removeTmp = false
-	return hex.EncodeToString(digest.Sum(nil)), nil
-}

internal/config/validate.go

@@ -9,7 +9,6 @@ import (
 	"strings"
 	"time"
 
-	"gitea.maximumdirect.net/eric/narratio/internal/artifactmodel"
 	"gitea.maximumdirect.net/eric/narratio/internal/artifactpolicy"
 	"gitea.maximumdirect.net/eric/narratio/internal/pathsafe"
 )
@@ -639,13 +638,9 @@ var scriptoriumArtifactKeyRE = regexp.MustCompile(`^[a-z][a-z0-9_]*$`)
 
 func validateScriptoriumInputSource(artifactName, inputName, source string, configuredArtifacts map[string]struct{}) (string, error) {
 	trimmedSource := strings.TrimSpace(source)
-	if isStaticSupportedScriptoriumInputSource(trimmedSource) {
-		return "", nil
-	}
-
-	if strings.HasPrefix(trimmedSource, "narratio.previous_session.artifact") {
-		referenced, ok := artifactpolicy.ParsePreviousSessionSource(trimmedSource)
-		if !ok {
+	descriptor, err := artifactpolicy.DescribeScriptoriumInputSource(trimmedSource)
+	if err != nil {
+		if errors.Is(err, artifactpolicy.ErrInvalidPreviousSessionSource) {
 			return "", fmt.Errorf(
 				"pipeline.scriptorium.artifacts.%s.inputs.%s.source %q must reference configured artifact key matching ^[a-z][a-z0-9_]*$",
 				artifactName,
@@ -653,20 +648,6 @@ func validateScriptoriumInputSource(artifactName, inputName, source string, conf
 				source,
 			)
 		}
-		if _, ok := configuredArtifacts[referenced]; !ok {
-			return "", fmt.Errorf(
-				"pipeline.scriptorium.artifacts.%s.inputs.%s.source %q references unknown artifact %q",
-				artifactName,
-				inputName,
-				source,
-				referenced,
-			)
-		}
-		return "", nil
-	}
-
-	referenced, ok := artifactpolicy.ParseConfiguredSource(trimmedSource)
-	if !ok {
 		return "", fmt.Errorf(
 			"pipeline.scriptorium.artifacts.%s.inputs.%s.source %q is unsupported",
 			artifactName,
@@ -674,28 +655,28 @@ func validateScriptoriumInputSource(artifactName, inputName, source string, conf
 			source,
 		)
 	}
-	if _, ok := configuredArtifacts[referenced]; !ok {
+	if err := artifactpolicy.ValidateInputConfiguredReference(descriptor, configuredArtifacts); err != nil {
+		var unknownConfigured *artifactpolicy.UnknownConfiguredArtifactError
+		if errors.As(err, &unknownConfigured) {
 			return "", fmt.Errorf(
 				"pipeline.scriptorium.artifacts.%s.inputs.%s.source %q references unknown artifact %q",
 				artifactName,
 				inputName,
 				source,
-			referenced,
+				unknownConfigured.ConfiguredKey,
 			)
 		}
-	return referenced, nil
+		return "", fmt.Errorf(
+			"pipeline.scriptorium.artifacts.%s.inputs.%s.source %q is unsupported",
+			artifactName,
+			inputName,
+			source,
+		)
 	}
-
-func isStaticSupportedScriptoriumInputSource(source string) bool {
-	if _, ok := artifactmodel.LookupRuntimeTranscriptArtifact(source); ok {
-		return true
-	}
-	switch source {
-	case "narratio.bounds.session":
-		return true
-	default:
-		return false
+	if descriptor.Source.Kind == artifactpolicy.SourceKindConfiguredArtifact {
+		return descriptor.Source.ConfiguredKey, nil
 	}
+	return "", nil
 }
 
 func validateEnvVarNameField(fieldName, value string) error {

internal/fileops/fileops.go

@@ -0,0 +1,128 @@
+package fileops
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+// WriteFileAtomic writes data to dst atomically via temp file + rename.
+func WriteFileAtomic(dst string, data []byte, perm os.FileMode) error {
+	if strings.TrimSpace(dst) == "" {
+		return fmt.Errorf("destination path is required")
+	}
+	if err := os.MkdirAll(filepath.Dir(dst), 0o755); err != nil {
+		return fmt.Errorf("create destination directory: %w", err)
+	}
+
+	base := filepath.Base(dst)
+	tmp, err := os.CreateTemp(filepath.Dir(dst), "."+base+".tmp-*")
+	if err != nil {
+		return fmt.Errorf("create temp file: %w", err)
+	}
+	tmpPath := tmp.Name()
+	removeTmp := true
+	defer func() {
+		if removeTmp {
+			_ = os.Remove(tmpPath)
+		}
+	}()
+
+	if _, err := tmp.Write(data); err != nil {
+		_ = tmp.Close()
+		return fmt.Errorf("write temp file: %w", err)
+	}
+	if err := tmp.Sync(); err != nil {
+		_ = tmp.Close()
+		return fmt.Errorf("sync temp file: %w", err)
+	}
+	if err := tmp.Close(); err != nil {
+		return fmt.Errorf("close temp file: %w", err)
+	}
+	if err := os.Chmod(tmpPath, perm); err != nil {
+		return fmt.Errorf("set temp file permissions: %w", err)
+	}
+	if err := os.Rename(tmpPath, dst); err != nil {
+		return fmt.Errorf("install temp file: %w", err)
+	}
+	removeTmp = false
+	return nil
+}
+
+// CopyFileAtomic copies src to dst atomically via temp file + rename.
+func CopyFileAtomic(src, dst string, perm os.FileMode) error {
+	_, err := CopyFileAtomicWithChecksum(src, dst, perm)
+	return err
+}
+
+// CopyFileAtomicWithChecksum copies src to dst atomically and returns the SHA-256 checksum.
+func CopyFileAtomicWithChecksum(src, dst string, perm os.FileMode) (string, error) {
+	if strings.TrimSpace(src) == "" || strings.TrimSpace(dst) == "" {
+		return "", fmt.Errorf("source and destination paths are required")
+	}
+
+	in, err := os.Open(src)
+	if err != nil {
+		return "", fmt.Errorf("open source file: %w", err)
+	}
+	defer func() { _ = in.Close() }()
+
+	if err := os.MkdirAll(filepath.Dir(dst), 0o755); err != nil {
+		return "", fmt.Errorf("create destination directory: %w", err)
+	}
+
+	base := filepath.Base(dst)
+	tmp, err := os.CreateTemp(filepath.Dir(dst), "."+base+".tmp-*")
+	if err != nil {
+		return "", fmt.Errorf("create temp file: %w", err)
+	}
+	tmpPath := tmp.Name()
+	removeTmp := true
+	defer func() {
+		if removeTmp {
+			_ = os.Remove(tmpPath)
+		}
+	}()
+
+	digest := sha256.New()
+	if _, err := io.Copy(io.MultiWriter(tmp, digest), in); err != nil {
+		_ = tmp.Close()
+		return "", fmt.Errorf("copy file: %w", err)
+	}
+	if err := tmp.Sync(); err != nil {
+		_ = tmp.Close()
+		return "", fmt.Errorf("sync temp file: %w", err)
+	}
+	if err := tmp.Close(); err != nil {
+		return "", fmt.Errorf("close temp file: %w", err)
+	}
+	if err := os.Chmod(tmpPath, perm); err != nil {
+		return "", fmt.Errorf("set temp file permissions: %w", err)
+	}
+	if err := os.Rename(tmpPath, dst); err != nil {
+		return "", fmt.Errorf("install temp file: %w", err)
+	}
+	removeTmp = false
+	return hex.EncodeToString(digest.Sum(nil)), nil
+}
+
+// InstallDownloadedTempFile installs a previously downloaded temp file at dst.
+func InstallDownloadedTempFile(tmpPath, dst string, perm os.FileMode) error {
+	if strings.TrimSpace(tmpPath) == "" || strings.TrimSpace(dst) == "" {
+		return fmt.Errorf("temp and destination paths are required")
+	}
+	if err := os.MkdirAll(filepath.Dir(dst), 0o755); err != nil {
+		return fmt.Errorf("create destination directory: %w", err)
+	}
+	if err := os.Chmod(tmpPath, perm); err != nil {
+		return fmt.Errorf("set temp file permissions: %w", err)
+	}
+	if err := os.Rename(tmpPath, dst); err != nil {
+		return fmt.Errorf("install downloaded file: %w", err)
+	}
+	return nil
+}

internal/fileops/fileops_test.go

@@ -0,0 +1,125 @@
+package fileops
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestWriteFileAtomicOverwritesAndLeavesNoTempFile(t *testing.T) {
+	root := t.TempDir()
+	dst := filepath.Join(root, "out", "value.txt")
+
+	if err := WriteFileAtomic(dst, []byte("one"), 0o644); err != nil {
+		t.Fatalf("WriteFileAtomic(first) error = %v", err)
+	}
+	if err := WriteFileAtomic(dst, []byte("two"), 0o644); err != nil {
+		t.Fatalf("WriteFileAtomic(second) error = %v", err)
+	}
+
+	data, err := os.ReadFile(dst)
+	if err != nil {
+		t.Fatalf("ReadFile() error = %v", err)
+	}
+	if string(data) != "two" {
+		t.Fatalf("file content = %q, want %q", string(data), "two")
+	}
+
+	assertNoMatchingTempFiles(t, filepath.Dir(dst), "."+filepath.Base(dst)+".tmp-")
+}
+
+func TestWriteFileAtomicCleansTempFileOnInstallFailure(t *testing.T) {
+	root := t.TempDir()
+	blockedPath := filepath.Join(root, "blocked")
+	if err := os.MkdirAll(blockedPath, 0o755); err != nil {
+		t.Fatalf("MkdirAll(blockedPath) error = %v", err)
+	}
+
+	err := WriteFileAtomic(blockedPath, []byte("data"), 0o644)
+	if err == nil {
+		t.Fatal("WriteFileAtomic() error = nil, want install failure")
+	}
+	assertNoMatchingTempFiles(t, root, ".blocked.tmp-")
+}
+
+func TestCopyFileAtomicWithChecksumMatchesDestination(t *testing.T) {
+	root := t.TempDir()
+	src := filepath.Join(root, "source.txt")
+	dst := filepath.Join(root, "out", "copied.txt")
+	if err := os.WriteFile(src, []byte("copied-data"), 0o644); err != nil {
+		t.Fatalf("WriteFile(source) error = %v", err)
+	}
+
+	checksum, err := CopyFileAtomicWithChecksum(src, dst, 0o644)
+	if err != nil {
+		t.Fatalf("CopyFileAtomicWithChecksum() error = %v", err)
+	}
+	wantChecksum := "6e5c3f239e28cc315d57b2fcfc24169369c44a25802c0616a6d7081707fd24df"
+	if checksum != wantChecksum {
+		t.Fatalf("checksum = %q, want %q", checksum, wantChecksum)
+	}
+
+	data, err := os.ReadFile(dst)
+	if err != nil {
+		t.Fatalf("ReadFile(destination) error = %v", err)
+	}
+	if string(data) != "copied-data" {
+		t.Fatalf("destination content = %q, want %q", string(data), "copied-data")
+	}
+	assertNoMatchingTempFiles(t, filepath.Dir(dst), ".copied.txt.tmp-")
+}
+
+func TestCopyFileAtomicCleansTempFileOnInstallFailure(t *testing.T) {
+	root := t.TempDir()
+	src := filepath.Join(root, "source.txt")
+	if err := os.WriteFile(src, []byte("copied-data"), 0o644); err != nil {
+		t.Fatalf("WriteFile(source) error = %v", err)
+	}
+
+	blockedPath := filepath.Join(root, "blocked")
+	if err := os.MkdirAll(blockedPath, 0o755); err != nil {
+		t.Fatalf("MkdirAll(blockedPath) error = %v", err)
+	}
+	err := CopyFileAtomic(src, blockedPath, 0o644)
+	if err == nil {
+		t.Fatal("CopyFileAtomic() error = nil, want install failure")
+	}
+	assertNoMatchingTempFiles(t, root, ".blocked.tmp-")
+}
+
+func TestInstallDownloadedTempFileSetsPermissions(t *testing.T) {
+	root := t.TempDir()
+	tmpPath := filepath.Join(root, ".payload.tmp")
+	dst := filepath.Join(root, "out", "payload.json")
+	if err := os.WriteFile(tmpPath, []byte("{\"ok\":true}\n"), 0o600); err != nil {
+		t.Fatalf("WriteFile(temp) error = %v", err)
+	}
+
+	if err := InstallDownloadedTempFile(tmpPath, dst, 0o644); err != nil {
+		t.Fatalf("InstallDownloadedTempFile() error = %v", err)
+	}
+	if _, err := os.Stat(tmpPath); !os.IsNotExist(err) {
+		t.Fatalf("temp file still exists: stat err = %v", err)
+	}
+	info, err := os.Stat(dst)
+	if err != nil {
+		t.Fatalf("Stat(destination) error = %v", err)
+	}
+	if info.Mode().Perm() != 0o644 {
+		t.Fatalf("destination mode = %o, want 644", info.Mode().Perm())
+	}
+}
+
+func assertNoMatchingTempFiles(t *testing.T, dir, prefix string) {
+	t.Helper()
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		t.Fatalf("ReadDir(%q) error = %v", dir, err)
+	}
+	for _, e := range entries {
+		if strings.HasPrefix(e.Name(), prefix) {
+			t.Fatalf("unexpected temp file residue: %s", filepath.Join(dir, e.Name()))
+		}
+	}
+}

internal/pathsafe/relative_destination_test.go

@@ -2,6 +2,8 @@ package pathsafe
 
 import (
 	"errors"
+	"path/filepath"
+	"strings"
 	"testing"
 )
 
@@ -41,3 +43,76 @@ func TestNormalizeRelativeDestination(t *testing.T) {
 		})
 	}
 }
+
+func TestJoinSlashRelativeUnderRoot(t *testing.T) {
+	root := filepath.Join(t.TempDir(), "session")
+
+	tests := []struct {
+		name    string
+		input   string
+		want    string
+		wantErr error
+	}{
+		{name: "valid relative", input: "artifacts/session_recap.md", want: filepath.Join(root, "artifacts", "session_recap.md")},
+		{name: "windows separators normalized", input: `artifacts\session_recap.md`, want: filepath.Join(root, "artifacts", "session_recap.md")},
+		{name: "reject empty", input: "", wantErr: ErrRelativePathRequired},
+		{name: "reject absolute", input: "/artifacts/session_recap.md", wantErr: ErrRelativePathAbsolute},
+		{name: "reject traversal", input: "../artifacts/session_recap.md", wantErr: ErrRelativePathEscape},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := JoinSlashRelativeUnderRoot(root, tt.input)
+			if tt.wantErr != nil {
+				if !errors.Is(err, tt.wantErr) {
+					t.Fatalf("JoinSlashRelativeUnderRoot() error = %v, want %v", err, tt.wantErr)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("JoinSlashRelativeUnderRoot() error = %v", err)
+			}
+			if got != tt.want {
+				t.Fatalf("JoinSlashRelativeUnderRoot() = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestSlashRelativeFromRoot(t *testing.T) {
+	root := filepath.Join(t.TempDir(), "session")
+	target := filepath.Join(root, "transcripts", "full.json")
+
+	got, err := SlashRelativeFromRoot(root, target)
+	if err != nil {
+		t.Fatalf("SlashRelativeFromRoot() error = %v", err)
+	}
+	if got != "transcripts/full.json" {
+		t.Fatalf("SlashRelativeFromRoot() = %q, want transcripts/full.json", got)
+	}
+
+	got, err = SlashRelativeFromRoot(root, `transcripts\full.json`)
+	if err != nil {
+		t.Fatalf("SlashRelativeFromRoot(relative with windows separators) error = %v", err)
+	}
+	if got != "transcripts/full.json" {
+		t.Fatalf("SlashRelativeFromRoot(relative with windows separators) = %q, want transcripts/full.json", got)
+	}
+}
+
+func TestSlashRelativeFromRootRejectsOutsideRoot(t *testing.T) {
+	root := filepath.Join(t.TempDir(), "session")
+	outside := filepath.Join(filepath.Dir(root), "outside", "file.txt")
+
+	_, err := SlashRelativeFromRoot(root, outside)
+	if !errors.Is(err, ErrRelativePathEscape) {
+		t.Fatalf("SlashRelativeFromRoot() error = %v, want %v", err, ErrRelativePathEscape)
+	}
+}
+
+func TestJoinSlashRelativeUnderRootRequiresRoot(t *testing.T) {
+	_, err := JoinSlashRelativeUnderRoot("", "artifacts/session_recap.md")
+	if err == nil || !strings.Contains(err.Error(), "root path is required") {
+		t.Fatalf("JoinSlashRelativeUnderRoot() error = %v, want root-required error", err)
+	}
+}

internal/pathsafe/root_scoped.go

@@ -0,0 +1,58 @@
+package pathsafe
+
+import (
+	"fmt"
+	"path/filepath"
+	"strings"
+)
+
+// JoinSlashRelativeUnderRoot validates a slash-style relative path and resolves
+// it under root. The returned path uses the host filepath separator.
+func JoinSlashRelativeUnderRoot(root, relative string) (string, error) {
+	rootClean := filepath.Clean(strings.TrimSpace(root))
+	if rootClean == "." || rootClean == "" {
+		return "", fmt.Errorf("root path is required")
+	}
+
+	normalized, err := NormalizeRelativeDestination(relative)
+	if err != nil {
+		return "", err
+	}
+
+	joined := filepath.Clean(filepath.Join(rootClean, filepath.FromSlash(normalized)))
+	rel, err := filepath.Rel(rootClean, joined)
+	if err != nil {
+		return "", fmt.Errorf("resolve relative path under root: %w", err)
+	}
+	if rel == "." || rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
+		return "", ErrRelativePathEscape
+	}
+	return joined, nil
+}
+
+// SlashRelativeFromRoot derives a slash-style relative path for target under
+// root. Target may be absolute or relative to root.
+func SlashRelativeFromRoot(root, target string) (string, error) {
+	rootClean := filepath.Clean(strings.TrimSpace(root))
+	if rootClean == "." || rootClean == "" {
+		return "", fmt.Errorf("root path is required")
+	}
+
+	targetClean := filepath.Clean(strings.TrimSpace(target))
+	if targetClean == "." || targetClean == "" {
+		return "", ErrRelativePathRequired
+	}
+	if !filepath.IsAbs(targetClean) {
+		targetClean = filepath.Clean(filepath.Join(rootClean, targetClean))
+	}
+
+	rel, err := filepath.Rel(rootClean, targetClean)
+	if err != nil {
+		return "", fmt.Errorf("derive path relative to root: %w", err)
+	}
+	normalized, err := NormalizeRelativeDestination(filepath.ToSlash(rel))
+	if err != nil {
+		return "", err
+	}
+	return normalized, nil
+}

internal/previouscache/previouscache.go

@@ -229,7 +229,11 @@ func artifactRelativePathCandidates(
 		candidates = append(candidates, normalized)
 	}
 
+	sourceDescriptor, err := artifactpolicy.PreviousSessionSourceDescriptorForConfiguredKey(artifactName)
 	sourceID := artifactpolicy.ConfiguredSourceID(artifactName)
+	if err == nil {
+		sourceID = sourceDescriptor.ConfiguredSourceID
+	}
 	if rel, ok := manifestArtifactRelativePathBySourceID(previousManifest, sourceID); ok {
 		appendCandidate(rel)
 		base := path.Base(rel)
@@ -309,11 +313,7 @@ func deriveManifestRelativePath(previousManifest *manifest.Manifest, localPath s
 	if !ok {
 		return "", false
 	}
-	rel, err := filepath.Rel(sessionRoot, trimmed)
-	if err != nil {
-		return "", false
-	}
-	normalized, err := pathsafe.NormalizeRelativeDestination(filepath.ToSlash(rel))
+	normalized, err := pathsafe.SlashRelativeFromRoot(sessionRoot, trimmed)
 	if err != nil {
 		return "", false
 	}
@@ -375,11 +375,7 @@ func relativeToSession(paths artifacts.SessionPaths, localPath string) (string,
 	if strings.TrimSpace(root) == "" {
 		return "", fmt.Errorf("session root is required")
 	}
-	rel, err := filepath.Rel(root, filepath.Clean(localPath))
-	if err != nil {
-		return "", fmt.Errorf("resolve previous-cache relative path: %w", err)
-	}
-	normalized, err := pathsafe.NormalizeRelativeDestination(filepath.ToSlash(rel))
+	normalized, err := pathsafe.SlashRelativeFromRoot(root, localPath)
 	if err != nil {
 		return "", fmt.Errorf("resolve previous-cache relative path: %w", err)
 	}

internal/stage/analyze.go

@@ -628,11 +628,11 @@ func resolveScriptoriumInput(
 	runtimeCatalog *artifacts.ArtifactCatalog,
 ) (string, bool, *artifacts.ResolvedSessionArtifact, error) {
 	source := strings.TrimSpace(inputCfg.Source)
-	classified, classifyErr := artifactpolicy.ClassifySource(source)
-	if classifyErr != nil {
-		return "", false, nil, classifyErr
+	descriptor, describeErr := artifactpolicy.DescribeScriptoriumInputSource(source)
+	if describeErr != nil {
+		return "", false, nil, describeErr
 	}
-	if classified.Kind == artifactpolicy.SourceKindPreviousArtifact {
+	if descriptor.Source.Kind == artifactpolicy.SourceKindPreviousArtifact {
 		resolved, err := artifacts.ResolvePreviousSessionArtifactWithCatalog(paths, m, source, runtimeCatalog)
 		if err == nil {
 			copy := resolved
@@ -657,13 +657,13 @@ func resolveScriptoriumInput(
 			return resolved.Path, true, &copy, nil
 		}
 		if errors.Is(err, artifacts.ErrSessionArtifactNotFound) {
-			if classified.Kind == artifactpolicy.SourceKindConfiguredArtifact {
+			if descriptor.Source.Kind == artifactpolicy.SourceKindConfiguredArtifact {
 				if inputCfg.Required {
 					return "", false, nil, fmt.Errorf("configured artifact source %q is unavailable", source)
 				}
 				return "", false, nil, nil
 			}
-			switch classified.ID {
+			switch descriptor.Source.ID {
 			case artifacts.ArtifactTranscriptPolished:
 				return "", false, nil, nil
 			case artifacts.ArtifactTranscriptFinal:

internal/stage/prepare_previous.go

@@ -8,6 +8,7 @@ import (
 	"sort"
 
 	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
+	"gitea.maximumdirect.net/eric/narratio/internal/fileops"
 	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
 	"gitea.maximumdirect.net/eric/narratio/internal/previouscache"
 )
@@ -54,8 +55,35 @@ func hydratePreviousSessionArtifacts(
 		if err := os.MkdirAll(filepath.Dir(record.LocalPath), 0o755); err != nil {
 			return nil, fmt.Errorf("create previous-session path directory for %q: %w", record.LocalPath, err)
 		}
-		if err := env.ObjectStore.Download(ctx, record.RemoteKey, record.LocalPath); err != nil {
-			return nil, fmt.Errorf("download previous-session object %q to %q: %w", record.RemoteKey, record.LocalPath, err)
+
+		base := filepath.Base(record.LocalPath)
+		tmp, err := os.CreateTemp(filepath.Dir(record.LocalPath), "."+base+".prepare-previous-*.tmp")
+		if err != nil {
+			return nil, fmt.Errorf("create previous-session temp file for %q: %w", record.LocalPath, err)
+		}
+		tmpPath := tmp.Name()
+		if err := tmp.Close(); err != nil {
+			_ = os.Remove(tmpPath)
+			return nil, fmt.Errorf("close previous-session temp file for %q: %w", record.LocalPath, err)
+		}
+		if err := func() error {
+			removeTmp := true
+			defer func() {
+				if removeTmp {
+					_ = os.Remove(tmpPath)
+				}
+			}()
+
+			if err := env.ObjectStore.Download(ctx, record.RemoteKey, tmpPath); err != nil {
+				return fmt.Errorf("download previous-session object %q to temp file: %w", record.RemoteKey, err)
+			}
+			if err := fileops.InstallDownloadedTempFile(tmpPath, record.LocalPath, 0o644); err != nil {
+				return fmt.Errorf("install previous-session object %q at %q: %w", record.RemoteKey, record.LocalPath, err)
+			}
+			removeTmp = false
+			return nil
+		}(); err != nil {
+			return nil, err
 		}
 		if record.Kind == preparePreviousInputKindArtifact {
 			if err := requireNonEmptyFile(record.LocalPath, "previous-session artifact "+record.RequirementName); err != nil {

internal/stage/run_local.go

@@ -9,6 +9,7 @@ import (
 	"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
 	"gitea.maximumdirect.net/eric/narratio/internal/config"
 	"gitea.maximumdirect.net/eric/narratio/internal/manifest"
+	"gitea.maximumdirect.net/eric/narratio/internal/pathsafe"
 )
 
 type runStageLayout struct {
@@ -92,18 +93,17 @@ func runLocalPathForCanonical(layout runStageLayout, sessionPaths artifacts.Sess
 	if cleanCanonical == "" {
 		return "", fmt.Errorf("canonical path is required")
 	}
-	rel, err := filepath.Rel(filepath.Clean(sessionPaths.Root), cleanCanonical)
+	rel, err := pathsafe.SlashRelativeFromRoot(sessionPaths.Root, cleanCanonical)
 	if err != nil {
 		return "", fmt.Errorf("derive session-relative path for %q: %w", cleanCanonical, err)
 	}
-	rel = filepath.Clean(rel)
-	if rel == "." || rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
-		return "", fmt.Errorf("canonical path %q is outside session root %q", cleanCanonical, sessionPaths.Root)
-	}
-	if rel == config.PathPreviousDirSegment || strings.HasPrefix(rel, config.PathPreviousDirSegment+string(filepath.Separator)) {
+	if rel == config.PathPreviousDirSegment || strings.HasPrefix(rel, config.PathPreviousDirSegment+"/") {
 		return cleanCanonical, nil
 	}
-	localPath := filepath.Join(layout.OutputsDir, rel)
+	localPath, err := pathsafe.JoinSlashRelativeUnderRoot(layout.OutputsDir, rel)
+	if err != nil {
+		return "", fmt.Errorf("resolve run-local output path for %q: %w", cleanCanonical, err)
+	}
 	if err := os.MkdirAll(filepath.Dir(localPath), 0o755); err != nil {
 		return "", fmt.Errorf("create run-local output parent for %q: %w", localPath, err)
 	}